Auto-sync API Docs from GitHub Actions on Every Push

Docs drift. You ship a new endpoint, your OpenAPI spec updates in the repo, but the hosted docs still show last week's schema. Customers file "your docs are wrong" tickets. You swear you'll set up a cron. You don't.

Outworx Docs solves this two ways. The easiest is spec URL auto-sync — point us at a URL and we re-fetch on a schedule. The more robust way is a GitHub Action that pushes the spec to us on every merge to main, so docs update the instant your API does.

This guide covers both, with the GitHub Action setup at the center.

Option 1 — Spec URL auto-sync (the 30-second option)

If your API serves the OpenAPI JSON at a public URL (e.g. https://api.yourcompany.com/openapi.json), you don't need GitHub Actions at all.

1. Open your project's API Spec tab on Outworx.
2. Click New version → From URL.
3. Paste the URL and pick a sync interval: hourly, daily, or weekly.
4. Done.

Every interval tick, Outworx fetches the URL, parses it, and bumps the version. Your hosted docs reflect the latest spec without any CI pipeline.

When this isn't enough: if your OpenAPI spec lives only in a git repo (never served publicly), or you want zero-lag updates the moment a PR merges, use the GitHub Action approach below.

Option 2 — GitHub Actions (zero-lag, push-based)

The flow:

1. You merge a PR to main that changes your OpenAPI spec
2. A GitHub Action fires on push
3. It POSTs the spec file to Outworx's upload API
4. Your hosted docs update within seconds

Step 1: Get your project upload token

Open your Outworx Docs dashboard → your project → Settings tab. Scroll to API access and copy the upload token. It looks like otwx_... and is scoped to one project.

Add it to your GitHub repo as a secret: Settings → Secrets and variables → Actions → New repository secret.

• Name: OUTWORX_TOKEN
• Value: your otwx_... token

Step 2: Drop in the workflow

Create .github/workflows/sync-docs.yml:

name: Sync API docs

on:
  push:
    branches: [main]
    paths:
      - "openapi.yaml"
      - "openapi.json"
      - "src/**/*.ts"  # trigger if your codegen emits a new spec

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

      - name: Regenerate spec (if your API auto-generates it)
        run: npm ci && npm run generate:openapi

      - name: Upload to Outworx Docs
        env:
          OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
        run: |
          curl -fsS -X POST \
            "https://docs.outworx.io/api/projects/<YOUR_SLUG>/upload" \
            -H "Authorization: Bearer $OUTWORX_TOKEN" \
            -H "Content-Type: application/yaml" \
            --data-binary "@openapi.yaml"

Replace <YOUR_SLUG> with your project slug (the subdomain before .docs.outworx.io).

Step 3: Optional — version your docs by git tag

If you want each git tag to become a new docs version rather than overwriting the default, tell the upload endpoint explicitly:

- name: Upload to Outworx Docs
  env:
    OUTWORX_TOKEN: ${{ secrets.OUTWORX_TOKEN }}
  run: |
    VERSION=${GITHUB_REF_NAME#v}  # v1.2.3 → 1.2.3
    curl -fsS -X POST \
      "https://docs.outworx.io/api/projects/<YOUR_SLUG>/upload?version=${VERSION}" \
      -H "Authorization: Bearer $OUTWORX_TOKEN" \
      -H "Content-Type: application/yaml" \
      --data-binary "@openapi.yaml"

Trigger on tag pushes instead:

on:
  push:
    tags:
      - "v*.*.*"

Now every release tag becomes a permanent docs version visitors can switch between. The latest tag becomes the default.

Verifying it works

After your first merge, check the Actions tab on GitHub — you should see "Sync API docs" green. On the Outworx side, go to API Spec → you should see a new version with Last synced: a few seconds ago.

If the action fails:

• 401 Unauthorized: the token is wrong, or the project slug in the URL doesn't match
• 413 Payload too large: specs over 2MB aren't accepted; trim unused definitions or switch to spec URL auto-sync (which handles large specs)
• 422 Unprocessable: the file isn't valid OpenAPI / Swagger / GraphQL; the error body explains which line

Why this pattern works so well

API specs are the source of truth for your contract with developers. When docs lag behind the spec, you pay in confusion, support tickets, and lost trust. Push-based sync flips the dynamic — you can't ship an API change that doesn't update the docs, because they're literally the same commit.

Combine this with Outworx's MCP server and your users' AI assistants will always have the latest spec too. Ship once, everything else catches up automatically.