{"id":28467461,"url":"https://github.com/oasdiff/oasdiff-action","last_synced_at":"2026-06-08T15:00:49.777Z","repository":{"id":164779769,"uuid":"639493209","full_name":"oasdiff/oasdiff-action","owner":"oasdiff","description":"GitHub action for comparing and detect breaking changes in OpenAPI specs","archived":false,"fork":false,"pushed_at":"2026-05-30T10:56:19.000Z","size":266,"stargazers_count":61,"open_issues_count":0,"forks_count":30,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-30T12:20:30.702Z","etag":null,"topics":["breaking-changes","changelog","diff","github-actions","openapi","openapi-spec","openapi3","swagger"],"latest_commit_sha":null,"homepage":"https://www.oasdiff.com/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oasdiff.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/Dockerfile","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-11T15:04:31.000Z","updated_at":"2026-05-30T10:55:46.000Z","dependencies_parsed_at":"2024-01-15T10:56:46.611Z","dependency_job_id":"87cd55c6-638d-4b5b-b79f-7f604a8a24a9","html_url":"https://github.com/oasdiff/oasdiff-action","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/oasdiff/oasdiff-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasdiff%2Foasdiff-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasdiff%2Foasdiff-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasdiff%2Foasdiff-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasdiff%2Foasdiff-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oasdiff","download_url":"https://codeload.github.com/oasdiff/oasdiff-action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oasdiff%2Foasdiff-action/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34067353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breaking-changes","changelog","diff","github-actions","openapi","openapi-spec","openapi3","swagger"],"created_at":"2025-06-07T07:39:09.444Z","updated_at":"2026-06-08T15:00:49.765Z","avatar_url":"https://github.com/oasdiff.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oasdiff-action\n[![breaking](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-breaking.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-breaking.yaml)\n[![changelog](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-changelog.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-changelog.yaml)\n[![diff](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-diff.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-diff.yaml)\n[![pr-comment](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-pr-comment.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-pr-comment.yaml)\n[![validate](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-validate.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-validate.yaml)\n[![verify](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-verify.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions/workflows/test-verify.yaml)\n\nGitHub Actions for comparing OpenAPI specs and detecting breaking changes, based on [oasdiff](https://github.com/oasdiff/oasdiff).\n\n## Contents\n\n- [Quick start](#quick-start)\n- [Free actions](#free-actions)\n  - [Check for breaking changes](#check-for-breaking-changes)\n  - [Generate a changelog](#generate-a-changelog)\n  - [Generate a diff report](#generate-a-diff-report)\n  - [Validate a single spec](#validate-a-single-spec)\n- [Configuring with `.oasdiff.yaml`](#configuring-with-oasdiffyaml)\n- [Spec paths](#spec-paths)\n- [Pro: Rich PR comment](#pro-rich-pr-comment)\n- [Pro: Verify your setup](#pro-verify-your-setup)\n\n## Quick start\n\nAdd this workflow to `.github/workflows/oasdiff.yaml` to block PRs that introduce breaking API changes.\nReplace `openapi.yaml` with the path to your OpenAPI spec:\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  breaking-changes:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/breaking@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n          fail-on: WARN\n```\n\nThis compares your spec on the PR branch against the base branch and fails the workflow if any breaking changes are found.\n\n---\n\n## Free actions\n\nThe following actions run the oasdiff CLI directly in your GitHub runner — no account or token required.\n\n### Check for breaking changes\n\nDetects breaking changes and writes inline GitHub annotations to the Actions summary. Fails the workflow when changes at or above the `fail-on` severity are found.\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  breaking-changes:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/breaking@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n          fail-on: WARN\n```\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref |\n| `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref |\n| `fail-on` | `''` | Fail with exit code 1 if changes are found at or above this severity | `ERR`, `WARN` |\n| `include-checks` | `''` | Include optional breaking change checks | check names (comma-separated) |\n| `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` |\n| `deprecation-days-beta` | `31` | Minimum sunset period (days) for deprecation of beta API endpoints | integer |\n| `deprecation-days-stable` | `180` | Minimum sunset period (days) for deprecation of stable API endpoints | integer |\n| `exclude-elements` | `''` | Exclude certain kinds of changes from the output | `endpoints`, `request`, `response` (comma-separated) |\n| `filter-extension` | `''` | Exclude paths and operations with an OpenAPI Extension matching this expression | regex |\n| `composed` | `false` | Run in composed mode | `true`, `false` |\n| `flatten-allof` | `false` | Merge allOf subschemas into a single schema before diff | `true`, `false` |\n| `err-ignore` | `''` | Path to a file containing regex patterns for error-level changes to ignore | file path |\n| `warn-ignore` | `''` | Path to a file containing regex patterns for warning-level changes to ignore | file path |\n| `output-to-file` | `''` | Write output to this file path instead of stdout | file path |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` |\n\n### Generate a changelog\n\nOutputs all changes (breaking and non-breaking) between two specs.\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  changelog:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/changelog@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n```\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref |\n| `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref |\n| `format` | `''` | Output format | `text`, `json`, `yaml`, `markdown`, `html` |\n| `level` | `''` | Minimum severity level to include in output | `INFO`, `WARN`, `ERR` |\n| `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` |\n| `exclude-elements` | `''` | Exclude certain kinds of changes from the output | `endpoints`, `request`, `response` (comma-separated) |\n| `filter-extension` | `''` | Exclude paths and operations with an OpenAPI Extension matching this expression | regex |\n| `composed` | `false` | Run in composed mode | `true`, `false` |\n| `flatten-allof` | `false` | Merge allOf subschemas into a single schema before diff | `true`, `false` |\n| `prefix-base` | `''` | Prefix to add to all paths in the base spec | string |\n| `prefix-revision` | `''` | Prefix to add to all paths in the revised spec | string |\n| `case-insensitive-headers` | `false` | Compare headers case-insensitively | `true`, `false` |\n| `template` | `''` | Custom Go template for output formatting | Go template string |\n| `output-to-file` | `''` | Write output to this file path instead of stdout | file path |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` |\n\n### Generate a diff report\n\nOutputs the raw structural diff between two specs.\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  diff:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/diff@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n```\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref |\n| `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref |\n| `fail-on-diff` | `false` | Fail with exit code 1 if any difference is found | `true`, `false` |\n| `format` | `yaml` | Output format | `yaml`, `json`, `text` |\n| `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` |\n| `exclude-elements` | `''` | Exclude certain kinds of changes from the output | `endpoints`, `request`, `response` (comma-separated) |\n| `filter-extension` | `''` | Exclude paths and operations with an OpenAPI Extension matching this expression | regex |\n| `composed` | `false` | Run in composed mode | `true`, `false` |\n| `flatten-allof` | `false` | Merge allOf subschemas into a single schema before diff | `true`, `false` |\n| `output-to-file` | `''` | Write output to this file path instead of stdout | file path |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` |\n\n### Validate a single spec\n\nValidates one OpenAPI spec against the OpenAPI and JSON Schema rules and writes an inline GitHub annotation for each finding. Unlike the other actions it takes a single spec, not a base/revision pair. Findings are classified by severity (error, warning, info); by default the workflow fails only on errors.\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - uses: oasdiff/oasdiff-action/validate@v0.0.57\n        with:\n          spec: 'openapi.yaml'\n```\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `spec` | — (required) | Path to the OpenAPI spec to validate | file path, URL, git ref |\n| `fail-on` | `''` | Fail with exit code 1 when a finding is at or above this severity (empty uses the oasdiff default, `ERR`) | `ERR`, `WARN`, `INFO` |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs | `true`, `false` |\n\nFor a non-blocking, report-only run, leave `fail-on` and set `continue-on-error: true` on the step. Outputs: `findings` (total), `error_count`, `warning_count`, `info_count`.\n\n---\n\n## Configuring with `.oasdiff.yaml`\n\nAll four actions (`breaking`, `changelog`, `diff`, `pr-comment`) automatically pick up a `.oasdiff.yaml` file from the root of your checked-out repository. This lets you keep CLI-flag-shaped configuration in source control instead of repeating the same `with:` block in every workflow file.\n\nDrop a `.oasdiff.yaml` next to your spec:\n\n```yaml\n# .oasdiff.yaml\nfail-on: ERR\nexclude-elements:\n  - description\n  - title\n  - summary\nerr-ignore: ./oasdiff-err-ignore.txt\n```\n\nThe actions read this file from the runner's `$GITHUB_WORKSPACE` (which `actions/checkout` populates), so no extra steps are needed.\n\n**Precedence**: action `with:` inputs override `.oasdiff.yaml` values, which override built-in defaults. Setting `fail-on: ERR` in YAML and leaving the action's `fail-on:` input empty applies the YAML value; setting both lets the action input win.\n\n**Legacy filename**: the older `oasdiff.yaml` (without the leading dot) still works as a back-compat fallback. New projects should prefer `.oasdiff.yaml` to match the dotfile convention used by `.eslintrc`, `.golangci.yml`, and similar tools.\n\n**Explicit path**: if your config lives somewhere else, set `OASDIFF_CONFIG` in the workflow `env:` to point at it:\n\n```yaml\n- uses: oasdiff/oasdiff-action/breaking@v0.0.57\n  env:\n    OASDIFF_CONFIG: ./config/oasdiff.yaml\n  with:\n    base: 'origin/${{ github.base_ref }}:openapi.yaml'\n    revision: 'HEAD:openapi.yaml'\n```\n\nFor the full list of supported keys and how relative paths inside the config file are resolved, see the [oasdiff configuration-file reference](https://github.com/oasdiff/oasdiff/blob/main/docs/CONFIG-FILES.md).\n\nAvailable since action `v0.0.47` (which ships oasdiff `v1.15.3`).\n\n---\n\n## Spec paths\n\nThe `base` and `revision` inputs accept:\n\n| Format | Example |\n|---|---|\n| Git ref (recommended) | `origin/${{ github.base_ref }}:openapi.yaml` |\n| Local file path | `openapi.yaml` |\n| http/s URL | `https://example.com/openapi.yaml` |\n\nWhen using git refs, you need to check out the repo and fetch the base branch:\n\n```yaml\n- uses: actions/checkout@v6\n- run: git fetch --depth=1 origin ${{ github.base_ref }}\n```\n\n\u003e `fetch-depth: 0` is not required — fetching only the base branch is sufficient.\n\n---\n\n## Pro: Rich PR comment\n\n`oasdiff/oasdiff-action/pr-comment` posts a single auto-updating comment on every PR that touches your API spec.\n\n**Getting started:** [Sign up for oasdiff Pro](https://www.oasdiff.com/pricing) to get your token, then follow the setup instructions to install the GitHub App, add your repo secret, and create the workflow.\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\njobs:\n  pr-comment:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/pr-comment@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}\n```\n\nThe comment shows a table of all changes, grouped by severity, with a **Review** link for each breaking change:\n\n| Severity | Change | Path | Review |\n|---|---|---|---|\n| 🔴 | request parameter became required | `GET /products` | ⏳ [Review](https://www.oasdiff.com/review/4a9fd2d5-5ac2-42f5-94cb-c911d6d41680?highlight=a570278809fa) |\n| 🔴 | api removed without deprecation | `DELETE /users/{userId}` | ⏳ [Review](https://www.oasdiff.com/review/4a9fd2d5-5ac2-42f5-94cb-c911d6d41680?highlight=bc9f61316c57) |\n| 🔴 | request parameter type changed | `GET /users/{userId}` | ⏳ [Review](https://www.oasdiff.com/review/4a9fd2d5-5ac2-42f5-94cb-c911d6d41680?highlight=b9a23e767b29) |\n\nEach **Review** link opens a hosted page with a side-by-side spec diff and **Approve / Reject** buttons. Approvals are tied to the change fingerprint and carry forward automatically when the branch is updated. A commit status check blocks the merge until every breaking change has been reviewed.\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref |\n| `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref |\n| `oasdiff-token` | — (required) | oasdiff API token — [sign up at oasdiff.com](https://www.oasdiff.com/pricing) | — |\n| `include-path-params` | `false` | Include path parameter names in endpoint matching | `true`, `false` |\n| `exclude-elements` | `''` | Exclude certain kinds of changes from the output | `endpoints`, `request`, `response` (comma-separated) |\n| `composed` | `false` | Run in composed mode | `true`, `false` |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false` to prevent SSRF on untrusted pull requests. Set `true` if your spec references external URLs or loads split files by file path | `true`, `false` |\n\n[Get oasdiff Pro →](https://www.oasdiff.com/pricing)\n\n## Pro: Verify your setup\n\n`oasdiff/oasdiff-action/verify` is a read-only check that confirms your setup works end to end. It posts no PR comment and sets no commit status. Run it on demand from the **Actions** tab (the \"Run workflow\" button).\n\nAdd it to the same workflow as `pr-comment`, guarded by event type, so one file handles both: `pr-comment` on pull requests, and `verify` when you click \"Run workflow\".\n\n```yaml\nname: oasdiff\non:\n  pull_request:\n    branches: [ \"main\" ]\n  workflow_dispatch:\njobs:\n  pr-comment:\n    if: github.event_name == 'pull_request'\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.base_ref }}\n      - uses: oasdiff/oasdiff-action/pr-comment@v0.0.57\n        with:\n          base: 'origin/${{ github.base_ref }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}\n  verify:\n    if: github.event_name == 'workflow_dispatch'\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - run: git fetch --depth=1 origin ${{ github.event.repository.default_branch }}\n      - uses: oasdiff/oasdiff-action/verify@v0.0.57\n        with:\n          base: 'origin/${{ github.event.repository.default_branch }}:openapi.yaml'\n          revision: 'HEAD:openapi.yaml'\n          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}\n```\n\nThe verify run renders a checklist in the workflow **Step Summary**:\n\n- ✅ GitHub Actions workflow is running\n- ✅ Connected to oasdiff (your `OASDIFF_TOKEN` secret)\n- ✅ oasdiff GitHub App installed on the repo\n- ✅ OpenAPI spec found and compared\n\nIt exits non-zero with a one-line hint for any check that fails, so a verify run is a clear pass/fail. (Reviewer access is checked separately on your setup page.)\n\n| Input | Default | Description | Accepted values |\n|---|---|---|---|\n| `base` | — (required) | Path to the base (old) OpenAPI spec | file path, URL, git ref |\n| `revision` | — (required) | Path to the revised (new) OpenAPI spec | file path, URL, git ref |\n| `oasdiff-token` | — (required) | oasdiff API token, [sign up at oasdiff.com](https://www.oasdiff.com/pricing) | — |\n| `allow-external-refs` | `false` | Resolve external `$ref`s. Defaults to `false`; set `true` if your spec references external URLs | `true`, `false` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasdiff%2Foasdiff-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foasdiff%2Foasdiff-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasdiff%2Foasdiff-action/lists"}