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
--spec	Yes	—	Path to your OpenAPI YAML or JSON file
--project	Yes	—	Project slug. Created automatically on first publish.
--environment	No	production	production \| staging \| dev
--governance	No	standard	standard \| strict \| off
--api-url	No	https://api.speclayer.net	Override for self-hosted deployments

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

GitHub Actions

.github/workflows/publish-spec.yml

name: Publish API Spec
on:
  push:
    branches: [main]
    paths: ['openapi/**', 'openapi.yaml', 'openapi.json']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Publish to SpecLayer
        run: |
          npx @speclayer/cli publish \
            --spec openapi/api.yaml \
            --project payments-api \
            --environment production \
            --governance strict
        env:
          SPECLAYER_API_KEY: ${{ secrets.SPECLAYER_KEY }}

Azure DevOps

azure-pipelines.yml

trigger:
  branches:
    include: [main]
  paths:
    include: [openapi/*]

steps:
  - checkout: self
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Use Node.js 20'
  - script: |
      npx @speclayer/cli publish \
        --spec openapi/api.yaml \
        --project payments-api \
        --environment production \
        --governance strict
    displayName: 'Publish spec to SpecLayer'
    env:
      SPECLAYER_API_KEY: $(SPECLAYER_KEY)

GitLab CI

.gitlab-ci.yml

publish-spec:
  stage: deploy
  image: node:20-alpine
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes: [openapi/**]
  script:
    - npx @speclayer/cli publish
        --spec openapi/api.yaml
        --project payments-api
        --environment production
        --governance strict
  # Add SPECLAYER_API_KEY in Settings > CI/CD > Variables

Jenkins

Jenkinsfile

pipeline {
  agent { label 'node' }
  stages {
    stage('Publish Spec') {
      when { branch 'main' }
      steps {
        withCredentials([string(credentialsId: 'speclayer-api-key',
                                variable: 'SPECLAYER_API_KEY')]) {
          sh """
            npx @speclayer/cli publish \
              --spec openapi/api.yaml \
              --project payments-api \
              --environment production \
              --governance strict
          """
        }
      }
    }
  }
}

CircleCI

.circleci/config.yml

version: 2.1
jobs:
  publish-spec:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Publish API Spec
          command: |
            npx @speclayer/cli publish \
              --spec openapi/api.yaml \
              --project payments-api \
              --environment production \
              --governance strict
workflows:
  main:
    jobs:
      - publish-spec:
          filters:
            branches:
              only: main

Bitbucket Pipelines

bitbucket-pipelines.yml

image: node:20

pipelines:
  branches:
    main:
      - step:
          name: Publish API Spec
          script:
            - npx @speclayer/cli publish
                --spec openapi/api.yaml
                --project payments-api
                --environment production
                --governance strict
          # Add SPECLAYER_API_KEY in Repository settings > Repository variables

CLI reference

All snippets use npx @speclayer/cli. No global install needed. Node.js 18+ is pre-installed on all major hosted CI runners (GitHub, GitLab, Azure, CircleCI, Bitbucket).

Run without installing

npx @speclayer/cli publish \
  --spec openapi/api.yaml \
  --project payments-api \
  --environment production \
  --governance strict

Or install globally

npm install -g @speclayer/cli

speclayer-cli publish \
  --spec openapi/api.yaml \
  --project payments-api \
  --environment production

# See all options
speclayer-cli publish --help