Publish from CI

Publish from CI when your OpenAPI file is generated or updated alongside your application. Each successful run sends the raw schema to the REST publishing endpoint. Identical content is deduplicated, so rerunning a job is safe.

Prepare the destination and tokenCopy Anchor Link

1. Create a SKMTC account, then choose the account handle, API slug, and visibility. For an organization API, the token's owner must be a member of that organization.
2. In Settings → Access tokens, generate a personal token with only publish:schemas and an expiration. Copy it immediately.
3. Save it as SKMTC_TOKEN in your CI secret store. Limit who can edit the publishing workflow and who can trigger deployments. Rotate the token from Settings and update the secret before it expires.

Choose private or public explicitly in the workflow. Many application schemas should be private. The publishing endpoint has no visibility default.

GitHub Actions exampleCopy Anchor Link

This workflow publishes openapi.yaml when it changes on main. Save it at .github/workflows/publish-openapi.yml, and create a GitHub Actions repository secret named SKMTC_TOKEN. Replace ada and billing with your destination. If your schema is generated, add its generation and validation steps before the publish step and point --data-binary at the generated file.

name: Publish OpenAPI to SKMTC

on:
  push:
    branches: [main]
    paths:
      - openapi.yaml
      - .github/workflows/publish-openapi.yml
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: skmtc-billing-publish
  cancel-in-progress: false

jobs:
  publish:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Publish schema
        env:
          SKMTC_TOKEN: ${{ secrets.SKMTC_TOKEN }}
        run: |
          test -n "$SKMTC_TOKEN"
          test -s openapi.yaml
          curl --fail-with-body --show-error --silent \
            --retry 3 \
            --request POST \
            --header "Authorization: Bearer $SKMTC_TOKEN" \
            --header 'Content-Type: application/octet-stream' \
            --data-binary @openapi.yaml \
            'https://api.skmtc.dev/v1/apis/publish?owner=ada&slug=billing&visibility=private&filename=openapi.yaml'

Review the destination in the final URL before merging the workflow:

Account:    ada
API slug:   billing
Visibility: private

The job fails on an HTTP error, including a missing token, invalid schema, account permission error, slug conflict, or visibility mismatch. Keep the token out of logs. If a new revision succeeds, the API page is https://skmtc.dev/ada/apis/billing; its Markdown twin is https://skmtc.dev/ada/apis/billing.md. Access to a private API still requires authorization.

Other CI systemsCopy Anchor Link

Use the same curl command in any CI runner after producing the OpenAPI file. Inject SKMTC_TOKEN from the runner's secret store, make the request only from a trusted branch or deployment job, and set owner, slug, and visibility explicitly. Use --data-binary @file so the file is sent as raw bytes. For a local or agent-driven publish, see Publish an API.