Add API Schema Drift Detection to GitHub Actions
Add a curl | npx typemorph-cli check step to your GitHub Actions workflow. It exits 1 on breaking changes and writes a summary to $GITHUB_STEP_SUMMARY — no OpenAPI spec, no extra services.
The problem
Schema drift from third-party APIs silently breaks production. Existing API monitoring tools require OpenAPI specs, paid plans, or complex config. You want something that works in CI with just npm and curl.
The solution
typemorph-cli check is a zero-config Node.js script. Add it to any GitHub Actions workflow: baseline is committed to git, the check step compares the live response against it, and the workflow fails if anything breaks.
Step-by-step
- 1
Create the workflow file
Add this to .github/workflows/api-schema.yml. The baseline file is read from the repo.
YAML
name: API Schema Check on: schedule: - cron: '0 9 * * 1-5' # weekdays at 09:00 UTC push: paths: - '.typemorph/**' jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Check /users schema run: | curl -s https://api.example.com/users/1 | \ npx typemorph-cli check \ --baseline .typemorph/users.json \ --format github >> $GITHUB_STEP_SUMMARY - 2
Commit your baseline
Run the check once locally to generate the baseline, then commit it.
Terminal
mkdir -p .typemorph curl -s https://api.example.com/users/1 \ | npx typemorph-cli check --baseline .typemorph/users.json git add .typemorph/users.json git commit -m "chore: add users API schema baseline" - 3
Check the Actions summary on failure
With --format github, breaking changes are written as a Markdown table to the Actions step summary — visible directly in the GitHub UI without reading raw logs.
Terminal
# Example step summary output: # | Field | Change | Severity | # |--------|-----------------|----------| # | email | string → missing | error | - 4
Monitor multiple endpoints
Add one step per endpoint. Use a matrix strategy for many endpoints.
YAML
- name: Check /orders schema run: | curl -s https://api.example.com/orders/1 | \ npx typemorph-cli check \ --baseline .typemorph/orders.json \ --format github >> $GITHUB_STEP_SUMMARY
Frequently asked
Do I need an OpenAPI spec file?
No. typemorph check infers the schema from the actual JSON response each time. No spec file, no YAML config.
How do I pass API authentication headers in CI?
Store your token as a GitHub Actions secret, then: curl -s -H "Authorization: Bearer ${{ secrets.API_TOKEN }}" https://api.example.com/endpoint | npx typemorph-cli check --baseline .typemorph/endpoint.json
Will it break my build on the first run?
No. If the baseline file does not exist yet, typemorph check creates it and exits 0. Only subsequent runs that find a diff will exit 1.
Can I use it with GitLab CI or Bitbucket Pipelines?
Yes. The command is plain Node.js/npm — it works in any CI environment. The --format github flag adds GitHub-specific summary output; omit it on other CI systems.