ci: add oasdiff breaking-change gate on PRs#1172
Merged
Merged
Conversation
The generated-client test matrix only catches spec changes that fail to compile. A renamed operationId, a removed parameter, or a changed type regenerates clients and their tests together, so everything stays green while every SDK consumer breaks — and build.yml then auto-publishes the regenerated clients to seven downstream repos on merge. oasdiff compares the compiled spec semantically: doc-only edits (descriptions, examples) pass, functional surface changes fail with --fail-on ERR. Both sides of the diff are the committed doc/compiled.json, which the existing compare-output job already keeps honest, so no recompile is needed. Intentional API changes opt out via the breaking-change-approved label; the job also posts the oasdiff changelog as a sticky PR comment so reviewers see the semantic diff instead of bundle noise. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
API changelog (oasdiff)Doc-only edits (descriptions, examples) do not appear here. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new GitHub Actions workflow to semantically detect breaking OpenAPI surface changes in pull requests (using oasdiff against the committed doc/compiled.json), with a label-based override and an automated changelog comment to aid reviewers.
Changes:
- Introduces
breaking-changes.ymlworkflow triggered on PR updates and label changes. - Checks out both PR head and base commit, runs
oasdiff changelog, and posts/updates a “sticky” PR comment. - Fails the workflow on detected breaking changes unless the
breaking-change-approvedlabel is present.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Manuel Boy (docstun)
approved these changes
Jun 11, 2026
Manuel Boy (docstun)
left a comment
Manuel Boy (docstun)
left a comment
Member
There was a problem hiding this comment.
Stephen Lumenta (@sbl) neat! If works as intended, we can bundle this into a shared action and bring this to the remaining OpenAPI schema repos for consistency.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The existing PR checks regenerate every client SDK and run its tests, which catches spec changes that break code generation. They cannot catch changes that regenerate cleanly but break consumers: a renamed operationId, a removed or renamed parameter, a changed type, or a flipped required flag regenerates clients and their tests together, so CI stays green while every published SDK changes its surface. On merge, build.yml then auto-publishes the regenerated clients to seven downstream repos.
This gap matters right now because an automated docs-quality sweep is about to open a batch of spec PRs that must be doc-only. A semantic gate makes "doc-only" machine-checked instead of reviewer-checked.
What
One new workflow,
breaking-changes.yml, onpull_request:oasdiff breaking <base>/doc/compiled.json <head>/doc/compiled.json --fail-on ERR. Description and example edits pass; functional surface changes fail. Both sides are the committed bundle, which the existingcompare-outputjob already keeps honest, so no recompile happens here.breaking-change-approvedlabel skips the gate (the workflow re-runs on label changes), so intentional API changes are a one-label action, not a workaround.oasdiff changelogoutput as a sticky PR comment, so reviewers see the semantic API diff instead of compiled-bundle noise.Verified locally against this repo's bundle: identical specs pass, a deleted operation fails with
api-removed-without-deprecation, a description-only edit passes.Follow-up (repo settings, not in this PR)
maincurrently has no required status checks (one approving review only), so any red check is mergeable. Suggest marking this job plus Lint, compare-output, compile-go, gradle, jest, phpunit, rspec, test, and unittest as required.🤖 Generated with Claude Code