{"id":28467461,"url":"https://github.com/oasdiff/oasdiff-action","last_synced_at":"2026-04-26T18:01:45.796Z","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-03-14T16:24:16.000Z","size":111,"stargazers_count":60,"open_issues_count":6,"forks_count":30,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-16T10:38:34.984Z","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-03-14T16:21:36.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":29,"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":31291171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-26T18:01:45.789Z","avatar_url":"https://github.com/oasdiff.png","language":"Shell","readme":"# oasdiff-action\n[![CI](https://github.com/oasdiff/oasdiff-action/actions/workflows/test.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions)\n\nGitHub Actions for comparing OpenAPI specs and detecting breaking changes, based on [oasdiff](https://github.com/oasdiff/oasdiff).\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.43\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.43\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\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.43\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\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.43\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\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.43\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\n[Get oasdiff Pro →](https://www.oasdiff.com/pricing)\n","funding_links":[],"categories":[],"sub_categories":[],"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"}