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 and no oasdiff account: the breaking-change detection runs in your CI. When the side-by-side review is enabled (the default) the action uploads the comparison to oasdiff.com, with the two specs encrypted in CI first; set review: false to keep everything inside your CI.

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 changes are found it also uploads the comparison and links to a full side-by-side review (the review input, on by default). The two specs are encrypted in CI before upload, so we never see them; set review: false to skip the upload. With github-token set (as below) the link is posted as a pull-request comment; otherwise, and on fork pull requests where the token is read-only, it falls back to the job summary. How to use the review.

name: oasdiff
on:
  pull_request:
    branches: [ "main" ]
permissions:
  contents: read
  pull-requests: write
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.57
        with:
          base: 'origin/${{ github.base_ref }}:openapi.yaml'
          revision: 'HEAD:openapi.yaml'
          fail-on: WARN
          github-token: ${{ github.token }}

Replace 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
review	true	Upload the comparison and link to a side-by-side review (encrypted in CI). Set false to skip the upload, so no spec leaves CI
github-token	""	Post the review link as a PR comment so reviewers see it on the PR (pass github.token and grant pull-requests: write). Omit to keep the link in the job summary only; fork PRs fall back to the summary

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

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

Next steps