https://github.com/oasdiff/oasdiff-action
GitHub action for comparing and detect breaking changes in OpenAPI specs
https://github.com/oasdiff/oasdiff-action
breaking-changes changelog diff github-actions openapi openapi-spec openapi3 swagger
Last synced: 9 days ago
JSON representation
GitHub action for comparing and detect breaking changes in OpenAPI specs
- Host: GitHub
- URL: https://github.com/oasdiff/oasdiff-action
- Owner: oasdiff
- License: apache-2.0
- Created: 2023-05-11T15:04:31.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-08T11:11:42.000Z (16 days ago)
- Last Synced: 2026-03-08T14:43:44.472Z (16 days ago)
- Topics: breaking-changes, changelog, diff, github-actions, openapi, openapi-spec, openapi3, swagger
- Language: Shell
- Homepage: https://www.oasdiff.com/
- Size: 77.1 KB
- Stars: 60
- Watchers: 4
- Forks: 30
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: changelog/Dockerfile
- License: LICENSE
Awesome Lists containing this project
README
# oasdiff-action
[](https://github.com/oasdiff/oasdiff-action/actions)
GitHub Actions for comparing OpenAPI specs and detecting breaking changes, based on [oasdiff](https://github.com/oasdiff/oasdiff).
## Spec paths
The `base` and `revision` inputs accept:
| Format | Example |
|---|---|
| Local file path | `specs/base.yaml` |
| http/s URL | `https://example.com/openapi.yaml` |
| Git ref | `origin/${{ github.base_ref }}:openapi.yaml` |
File paths and git refs require the repository to be checked out first:
```yaml
- uses: actions/checkout@v6
- run: git fetch --depth=1 origin ${{ github.base_ref }}
- uses: oasdiff/oasdiff-action/breaking@v0.0.31
with:
base: 'origin/${{ github.base_ref }}:openapi.yaml'
revision: 'HEAD:openapi.yaml'
```
> A targeted `git fetch` is needed so that `origin/${{ github.base_ref }}` is available. `fetch-depth: 0` is not required — fetching only the base branch is sufficient.
---
## 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.
```yaml
- uses: oasdiff/oasdiff-action/breaking@v0.0.31
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.
```yaml
- uses: oasdiff/oasdiff-action/changelog@v0.0.31
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.
```yaml
- uses: oasdiff/oasdiff-action/diff@v0.0.31
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@v0.0.31` 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.
```yaml
- uses: oasdiff/oasdiff-action/pr-comment@v0.0.31
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 — [sign up at oasdiff.com](https://oasdiff.com) 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 →](https://www.oasdiff.com/pricing)