GitHub Action
Free CI integration: flag breaking API changes on every pull request, inline.
How it works
The oasdiff/oasdiff-action/breaking Action runs on pull requests and compares your API spec in the PR branch against the spec on the base branch. Breaking changes show up inline in the "Files changed" tab as ::error:: annotations. No sign-up, no token, no oasdiff account required, the Action runs entirely inside your CI using your repository's built-in GITHUB_TOKEN.
Want a rich PR comment with approve/reject and a commit-status check that blocks merge until breaking changes are signed off? See the oasdiff Pro setup guide. Pro uses a different Action step on top of the same workflow.
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 (how to use it).
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.51
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, diff, and validate actions support a similar set of inputs. The validate action runs against a single spec (no base / revision split), failing the workflow when the spec violates OpenAPI or JSON Schema rules. See the full reference on GitHub →
Configuring with .oasdiff.yaml
Each action automatically picks up a .oasdiff.yaml file from the root of the checked-out repository. Keep CLI-flag-shaped configuration in source control instead of repeating the same with: block in every workflow.
# .oasdiff.yaml at the repo root
fail-on: ERR
exclude-elements:
- description
- title
- summary
err-ignore: ./oasdiff-err-ignore.txtAction with: inputs override values in the file. The legacy oasdiff.yaml filename (no leading dot) still works as a back-compat fallback.
For configs outside the repo root, set OASDIFF_CONFIG in the workflow env: block. For the full list of supported keys, see the oasdiff configuration-file reference.