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. If breaking changes are detected, it can fail the check and post inline annotations.
Quick setup
Add this workflow file to your repository at .github/workflows/oasdiff.yml:
name: API Breaking Change Check
on:
pull_request:
paths:
- 'openapi/**' # adjust to your spec location
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: oasdiff/oasdiff-action@v0
with:
base: 'origin/${{ github.base_ref }}:openapi/openapi.yaml'
revision: 'HEAD:openapi/openapi.yaml'
fail-on-diff: 'BREAKING'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-diff | "" | Fail on BREAKING, ERR, or WARN level changes |
| format | text | Output format: text, json, yaml, githubactions, markdown |
| lang | en | Language: en, ru, pt, es |
Free: inline GitHub annotations
With format: githubactions, oasdiff emits ::error:: annotations that GitHub displays inline on the changed files in a pull request — for free, with no sign-up required.
- uses: oasdiff/oasdiff-action@v0
with:
base: 'origin/${{ github.base_ref }}:openapi/openapi.yaml'
revision: 'HEAD:openapi/openapi.yaml'
fail-on-diff: 'BREAKING'
format: 'githubactions'Pro: rich PR comment
oasdiff Pro posts a formatted pull request comment that shows breaking changes, non-breaking changes, and a full changelog — visible to every reviewer without leaving GitHub.
⚠️ 2 Breaking Changes Detected
• response-property-enum-value-removed: DELETE /users/{id}
• request-property-became-required: POST /orders
📋 3 Other Changes
• endpoint-added: GET /users/{id}/preferences
• response-property-added-not-breaking: GET /orders
• response-optional-property-added: GET /products