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.

oasdiff[bot]commented

🔴 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.

⚙️

Prerequisite: install the GitHub App

oasdiff posts PR comments and commit statuses as a GitHub App, not as your personal account. You need to install the oasdiff GitHub App on each repository before the action can write to it.

Add your OASDIFF_TOKEN as a repository secret and use the pr-comment action step:

jobs:
  oasdiff:
    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.40-beta.3
        with:
          base: 'origin/${{ github.base_ref }}:openapi/openapi.yaml'  # replace with your spec path
          revision: 'HEAD:openapi/openapi.yaml'                          # replace with your spec path
          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}

Replace openapi/openapi.yaml with the path to your OpenAPI spec file.

Get Pro →View on GitHub

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: 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@v6

      - run: git fetch --depth=1 origin ${{ github.base_ref }}

      - uses: oasdiff/oasdiff-action/breaking@v0.0.40-beta.3
        with:
          base: 'origin/${{ github.base_ref }}:openapi/openapi.yaml'  # replace with your spec path
          revision: 'HEAD:openapi/openapi.yaml'                          # replace with your spec path
          fail-on: ERR

Replace openapi/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 →