GitHub Actions

Automatically publish your OpenAPI spec to SpecVault on every successful deployment using GitHub Actions.

Prerequisites

• A SpecVault API token (see API Tokens)
• The service ID for the API you want to publish (found in the service Settings tab)
• Your SpecVault instance URL (e.g. https://specvault.sentinelflux.in)

Store secrets in GitHub

In your GitHub repository, go to Settings → Secrets and variables → Actions and add:

• SPECVAULT_TOKEN — your SpecVault API token
• SPECVAULT_SERVICE_ID — the service ID (or hardcode it in the workflow)

Complete workflow example

This workflow runs on every push to main, builds your application, runs tests, and — on success — publishes the OpenAPI spec to SpecVault:

name: Deploy and publish spec

on:
  push:
    branches: [main]

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

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        run: pytest

      - name: Deploy application
        run: ./scripts/deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

      - name: Publish spec to SpecVault
        run: |
          curl -sf -X POST \
            "${{ vars.SPECVAULT_URL }}/api/services/${{ secrets.SPECVAULT_SERVICE_ID }}/specs" \
            -H "Authorization: Bearer ${{ secrets.SPECVAULT_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"spec_url": "${{ vars.API_BASE_URL }}/openapi.json"}'

Uploading a spec file instead of a URL

If your spec is generated as a file during the build (rather than served at a URL), upload it directly:

      - name: Publish spec to SpecVault
        run: |
          curl -sf -X POST \
            "${{ vars.SPECVAULT_URL }}/api/services/${{ secrets.SPECVAULT_SERVICE_ID }}/specs" \
            -H "Authorization: Bearer ${{ secrets.SPECVAULT_TOKEN }}" \
            -F "file=@openapi.yaml"

Publishing only on tag releases

If you want to publish specs only on versioned releases rather than every push:

on:
  push:
    tags:
      - 'v*'

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

      - name: Publish spec
        run: |
          curl -sf -X POST \
            "https://specvault.sentinelflux.in/api/services/${{ secrets.SPECVAULT_SERVICE_ID }}/specs" \
            -H "Authorization: Bearer ${{ secrets.SPECVAULT_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d "{\"spec_url\": \"https://api.yourcompany.com/openapi.json\", \"version_label\": \"${{ github.ref_name }}\"}"

Verifying the publish

After the workflow runs, check the SpecVault dashboard for your service. The new version should appear in the Versions tab within a few seconds. If breaking changes were detected, subscriber alerts are sent automatically at that point.