SpecDoc

CI/CD Integration

Add one step to your existing pipeline. Every run publishes a versioned spec, runs governance checks, detects breaking changes, and rebuilds your developer portal.

All configuration options

Option	Required	Default	Description
specFile	Yes	—	Path to your OpenAPI YAML or JSON file
projectSlug	Yes	—	Unique project identifier. Created on first publish.
environment	No	production	production \| staging \| dev
governancePolicy	No	standard	off \| standard \| strict \| path to custom file
governanceMode	No	enforce	enforce \| report-only
breakingChange	No	warn	fail \| warn \| off
publishPortal	No	true	Rebuild the developer portal after publish
portalConfig	No	—	Path to .speclayer/portal.yaml for branding

Store your API key in your CI/CD platform's secret store — never commit it to source control. The key needs the publish:specs scope.

Per-platform examples

Azure DevOps

azure-pipelines.yml

steps:
  - task: speclayer-publish@1
    displayName: 'Publish API spec'
    inputs:
      specFile: 'openapi/api.yaml'
      projectSlug: 'payments-api'
      environment: 'production'
      governancePolicy: 'strict'
      governanceMode: 'enforce'
      breakingChange: 'fail'
      publishPortal: true
    env:
      SPECLAYER_API_KEY: $(SPECLAYER_KEY)

GitHub Actions

.github/workflows/docs.yml

name: Publish API Docs

on:
  push:
    branches: [main]
    paths:
      - 'openapi/**'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: speclayer/publish-action@v1
        with:
          spec-file: openapi/api.yaml
          project-slug: payments-api
          environment: production
          governance-policy: strict
          breaking-change: fail
          publish-portal: true
        env:
          SPECLAYER_API_KEY: ${{ secrets.SPECLAYER_KEY }}

GitLab CI

.gitlab-ci.yml

publish-docs:
  stage: deploy
  image: speclayer/cli:latest
  only:
    - main
  script:
    - speclayer publish
        --spec openapi/api.yaml
        --project payments-api
        --env production
        --policy strict
        --breaking-change fail
        --portal
  variables:
    SPECLAYER_API_KEY: $SPECLAYER_KEY

Jenkins

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Publish API Docs') {
      steps {
        withCredentials([string(credentialsId: 'SPECLAYER_KEY',
                                variable: 'SPECLAYER_API_KEY')]) {
          sh """
            docker run --rm \
              -e SPECLAYER_API_KEY \
              -v $(pwd):/workspace \
              speclayer/cli:latest publish \
                --spec /workspace/openapi/api.yaml \
                --project payments-api \
                --env production \
                --policy strict \
                --portal
          """
        }
      }
    }
  }
}

CircleCI

.circleci/config.yml

version: 2.1

orbs:
  speclayer: speclayer/publish@1

jobs:
  publish-docs:
    executor: speclayer/default
    steps:
      - checkout
      - speclayer/publish:
          spec-file: openapi/api.yaml
          project-slug: payments-api
          environment: production
          governance-policy: strict
          publish-portal: true

workflows:
  docs:
    jobs:
      - publish-docs:
          filters:
            branches:
              only: main

Bitbucket Pipelines

bitbucket-pipelines.yml

pipelines:
  branches:
    main:
      - step:
          name: Publish API Docs
          image: speclayer/cli:latest
          script:
            - speclayer publish
                --spec openapi/api.yaml
                --project payments-api
                --env production
                --policy strict
                --portal
          variables:
            SPECLAYER_API_KEY: $SPECLAYER_KEY

CLI reference

All integrations use the speclayer/cli Docker image under the hood. You can also use the CLI directly:

Install

npm install -g @speclayer/cli
# or use Docker
docker pull speclayer/cli:latest

Publish command

speclayer publish \
  --spec openapi/api.yaml \
  --project payments-api \
  --env production \
  --policy strict \
  --breaking-change fail \
  --portal

# See all options
speclayer publish --help

Developer Portals

AI Enrichment