oasdiff-action

GitHub Actions for comparing OpenAPI specs and detecting breaking changes, based on oasdiff.

Free actions

The following actions run the oasdiff CLI directly in your GitHub runner — no account or token required.

Check for breaking changes

Detects breaking changes and writes inline GitHub annotations (::error::) to the Actions summary. Fails the workflow if breaking changes are found.

- uses: oasdiff/oasdiff-action/breaking@main
  with:
    base: 'specs/base.yaml'
    revision: 'specs/revision.yaml'

The result is also available as a step output named breaking.

Input	CLI flag	Default
fail-on	--fail-on	''
include-checks	--include-checks	''
include-path-params	--include-path-params	false
deprecation-days-beta	--deprecation-days-beta	31
deprecation-days-stable	--deprecation-days-stable	180
exclude-elements	--exclude-elements	''
filter-extension	--filter-extension	''
composed	-c	false
output-to-file	N/A	''

Generate a changelog

Outputs all changes (breaking and non-breaking) between two specs.

- uses: oasdiff/oasdiff-action/changelog@main
  with:
    base: 'specs/base.yaml'
    revision: 'specs/revision.yaml'

Input	CLI flag	Default
format	--format	''
level	--level	''
include-path-params	--include-path-params	false
exclude-elements	--exclude-elements	''
filter-extension	--filter-extension	''
composed	-c	false
prefix-base	--prefix-base	''
prefix-revision	--prefix-revision	''
case-insensitive-headers	--case-insensitive-headers	false
template	--template	''
output-to-file	N/A	''

Generate a diff report

Outputs the raw structural diff between two specs.

- uses: oasdiff/oasdiff-action/diff@main
  with:
    base: 'specs/base.yaml'
    revision: 'specs/revision.yaml'

Input	CLI flag	Default
fail-on-diff	--fail-on-diff	false
format	--format	yaml
include-path-params	--include-path-params	false
exclude-elements	--exclude-elements	''
filter-extension	--filter-extension	''
composed	-c	false
output-to-file	N/A	''

---

Pro: Rich PR comment

oasdiff/oasdiff-action/pr-comment@main posts a single auto-updating comment on the PR timeline every time the spec changes. Changes are grouped by severity (breaking → warnings → info) with links to the affected source lines.

- uses: oasdiff/oasdiff-action/pr-comment@main
  with:
    base: 'specs/base.yaml'
    revision: 'specs/revision.yaml'
    oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}

Input	Description	Required
base	Path to the base (old) OpenAPI spec	Yes
revision	Path to the revised (new) OpenAPI spec	Yes
oasdiff-token	oasdiff API token — contact us to get one	Yes
github-token	GitHub token for posting the comment	No (defaults to ${{ github.token }})
include-path-params	Include path parameter names in endpoint matching	No
exclude-elements	Exclude certain kinds of changes	No
composed	Run in composed mode	No

An OASDIFF_TOKEN is issued per GitHub organization. See pricing →