GitHub Action
Block merges that break your API contract — automatically, on every pull request.
How it works
The oasdiff/oasdiff-action GitHub Action runs on pull requests and compares your API spec in the PR branch against the spec on the base branch. Two tiers are available: a free annotation mode and a Pro mode with a full review and approval workflow.
Pro: rich PR comment
With an OASDIFF_TOKEN, oasdiff Pro posts a formatted pull request comment — one per PR, auto-updated on each push — listing every change with severity, endpoint, and a per-change review link.
🔴 2 breaking changes · 🟡 1 warning
| Severity | Change | Path | Review |
|---|---|---|---|
| 🔴 | removed the success response with the status '200' | POST /api/v1/groups | ✅ Approved by @alice |
| 🔴 | request body property became required | POST /api/v1/orders | ⏳ Pending review |
| 🟡 | response body property became deprecated | GET /api/v1/users | — |
Compared at commit a3f9c12 · 📋 Review & approve changes
Pro: review and approve breaking changes
The PR comment links to a hosted review page where your team can approve or reject each breaking change before the PR is merged. Approvals carry forward automatically — if the same breaking change appears in a later commit, it stays approved.
A commit status check (oasdiff / API changes) is posted on each push. It stays pending until all breaking changes have been reviewed, then flips to success. Pair it with a branch protection rule to enforce sign-off before merge.
The Sign up for oasdiff Pro to get your token, then follow the setup instructions to install the GitHub App, add your repo secret, and create the workflow file.
name: oasdiff
on:
pull_request:
branches: [ "main" ]
jobs:
pr-comment:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- run: git fetch --depth=1 origin ${{ github.base_ref }}
- uses: oasdiff/oasdiff-action/pr-comment@v0.0.46
with:
base: 'origin/${{ github.base_ref }}:openapi.yaml'
revision: 'HEAD:openapi.yaml'
oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}Replace openapi.yaml with the path to your OpenAPI spec file.
Free: inline GitHub annotations
The breaking action automatically emits ::error:: annotations that GitHub displays inline on the changed files in a pull request — no sign-up required. When breaking changes are found, it also emits a ::notice:: link to a free review page where you can see the full side-by-side diff.
name: oasdiff
on:
pull_request:
branches: [ "main" ]
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- run: git fetch --depth=1 origin ${{ github.base_ref }}
- uses: oasdiff/oasdiff-action/breaking@v0.0.46
with:
base: 'origin/${{ github.base_ref }}:openapi.yaml'
revision: 'HEAD:openapi.yaml'
fail-on: WARNReplace openapi.yaml with the path to your OpenAPI spec file.
Configuration options
| Input | Default | Description |
|---|---|---|
| base | (required) | Path/ref of the base OpenAPI spec |
| revision | (required) | Path/ref of the revised OpenAPI spec |
| fail-on | "" | Fail with exit code 1 if changes are found at or above this severity: ERR, WARN |
| include-path-params | false | Include path parameter names in endpoint matching |
| deprecation-days-beta | 31 | Minimum sunset period (days) for beta API deprecations |
| deprecation-days-stable | 180 | Minimum sunset period (days) for stable API deprecations |
| exclude-elements | "" | Exclude certain kinds of changes: endpoints, request, response |
| filter-extension | "" | Exclude paths/operations matching this OpenAPI Extension regex |
| composed | false | Run in composed mode (glob patterns for multiple spec files) |
| flatten-allof | false | Merge allOf subschemas into a single schema before diff |
| err-ignore | "" | Path to a file of regex patterns for error-level changes to ignore |
| warn-ignore | "" | Path to a file of regex patterns for warning-level changes to ignore |
| output-to-file | "" | Write output to this file path instead of stdout |
The changelog and diff actions support a similar set of inputs. See the full reference on GitHub →