Agent Wranglers

API-88Recommended

Check every schema change for breaking changes in CI

Compare each change to a GraphQL schema or protobuf file with the version on the main branch in CI. Fail the build on a breaking change unless the pull request carries an approved label.

By Agent Wranglers. Updated .

How to do it

A removed field or a changed type is easy to miss in review and breaks clients you cannot see. Tools such as buf breaking for protobuf and GraphQL Inspector for GraphQL read both versions and list each break. Keep the schema file in the repository as the contract, as write the contract first says for OpenAPI. Generate clients from it as generate docs and clients from the contract says.

Examples

Shell example

buf breaking --against '.git#branch=main'
npx graphql-inspector diff 'git:origin/main:schema.graphql' schema.graphql

How to check

Open a test pull request that removes one field from the schema. CI fails and names the field. With the approved label, the same change passes.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/api-design/graphql-and-grpc/schema-breaking-checks">Agent Wranglers API design playbook</a>. In code you write, add a comment next to it with the same link.