Check API changes in GitHub pull requests

Check API changes, keep the full report, and move on.

The openapi-changes Action compares one OpenAPI root file and its local references. It adds a short GitHub job summary, saves full reports, and fails the check when breaking changes are found. No Doctor account is needed.

Add the workflow

Save this as .github/workflows/api-changes.yaml. Change spec to your root specification path.

name: API changes
on: pull_request
permissions:
  contents: read
jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: pb33f/openapi-changes@v0.3.0
        with:
          spec: openapi.yaml
          base: ${{ github.event.pull_request.base.sha }}
          head: ${{ github.event.pull_request.head.sha }}

Open a pull request that changes the specification. Under Actions, open the API changes run to see the summary. Download its openapi-changes artifact for the full JSON, Markdown, and HTML reports. Open report.html locally to explore the changes.

To block merges on a failed check, select the api job in your repository’s required status checks.

The Action runs on Linux and builds the Go CLI and runner from the pinned commit. The first run needs time to download and compile dependencies. It does not execute code from the repository being compared.

Choose the policy

The default is fail-on: breaking. Add fail-on: changes to fail on any change, or fail-on: none to retain reports without blocking detected changes. Invalid specifications and failed analysis always fail the Action.

Input	Use
`spec`	Required repository-relative root file, present in both revisions.
`base`, `head`	Required revisions already available in the checkout. Use full commit SHAs.
`breaking-rules`	Optional repository-relative rules file, read from the base revision.
`fail-on`	`breaking`, `changes`, or `none`. Defaults to `breaking`.
`artifact-name`	Defaults to `openapi-changes`. Use a unique name for each matrix job or Action call.

With no breaking-rules input, the Action uses engine defaults. It ignores automatic rules files in the checkout and home directory. A PR cannot relax its own policy by editing a rules file.

Both revisions must exist in the checkout. The Action does not fetch missing revisions. Local $ref files resolve from their selected revision, not the working tree. Remote references are disabled.

Use pull_request with read-only permissions, including for fork PRs. Do not run PR code through pull_request_target.

Read the result

The outcome output is passed, policy-failed, or analysis-error. The Action uploads reports before applying the policy, so breaking changes still have a report. Failed analysis retains diagnostics and does not produce a clean result.

Other outputs are base-sha, head-sha, total, breaking, and artifact-path. Counts use the human summary’s JSONPath + property deduplication. Full JSON retains its existing raw counts, which can be higher. An unchanged comparison produces an explicit no-change report.

Artifacts can contain specification content. Repository artifact access and retention settings apply.

For a local short report, use compact Markdown.

Continue in Doctor

Use OpenAPI Doctor for workspace history, diagnostics, and pipeline controls. Sign in and connect the repository through its normal flow. The report link does not upload a specification or save the comparison to a Doctor workspace.