Ship GraphQL schema changes
with confidence.

Nitro's schema checks test a proposed change against the operations your clients rely on in production. Breaking change detection shows what would break, so you can fix it before it reaches users.

Start for freeRead client registry docs
schema.graphql
@@ type Order @@
4141 type Order {
4242 id: ID!
43+ totalAmount: Money!
43- total: Float!
RRegistryBREAKINGline 43

Removing Order.total breaks queries that still select it. Queries and mutations from 3 client versions published to this stage are affected. Deprecate it, then remove it after those versions are retired or unpublished from the stage.

4444 status: OrderStatus!
45+ placedAt: DateTime @deprecated(reason: "use createdAt")
4546 }
registry check failed1 breaking · 1 dangerous · 1 safe

Breaking changes fail the pull request.

Nitro fails the pull request when a proposed change would break an operation your clients have published. The problem shows up as a red status on the PR, not as an incident after release. Mark it as required and the merge button stays locked until the schema is safe.

#482 Add Money type
FAILRegistry check1 breaking · 2 safe
Schema validation — breaking changeOrder.total removed
Schema validation — additiveMoney, totalAmount added
Client compatibility — partner appvalidating...
Required CI policy blocks merge until checks pass.Re-run check

See which clients a change would break.

Validation runs against the set of operations your client versions have published to that environment. Each client gets its own result: a change that is safe for web can still break mobile, and you see that before you merge.

client registry·impact of #482
clientoperations passingstatus
web
production
5/5
OK
mobile
production
3/5
at risk
partner
sandbox
none published
outside result
internal-admin
staging
6/6
OK

Every environment is its own gate.

Development, staging, and production each hold their own published operations, so the same change is validated against what actually runs in each of them. A change that passes staging can still fail production, because different client versions are published there.

Development
Passed
Staging
Failed
Production

Run the checks in the CI you already have.

The validate, upload, and publish steps ship as ready-made GitHub Actions and Azure Pipelines tasks, both wrapping the Nitro CLI.

GitHub Actions

.github/workflows/ci.yml
- uses: ChilliCream/nitro-schema-validate@v16 with: api-id: ${{ vars.NITRO_API_ID }} api-key: ${{ secrets.NITRO_API_KEY }} schema-file: ./schema.graphql stage: production comment-mode: review
✓ check passedGitHub Marketplace

Azure Pipelines

azure-pipelines.yml
- task: NitroSchemaValidate@16 inputs: authenticationType: serviceConnection nitroServiceConnection: nitro-prod apiId: $(NITRO_API_ID) schemaFile: ./schema.graphql stage: production
✓ task succeededVisual Studio Marketplace

Any other CI

shell
$ nitro schema validate \ --api-id $NITRO_API_ID \ --schema-file schema.graphql \ --stage production validating against production… ✓ no breaking changes
✓ exit 0CLI reference

Keep the full history of your schema.

Every upload and publish adds a version to the registry, giving you a browsable record of how the API evolved: what changed in each version, how severe it was, and when a blocked removal finally cleared. Answering 'when did this field change and why' no longer means digging through merge commits.

schema history
  1. v12add Cart.discountSAFE
  2. v13deprecate Order.placedAtDANGEROUS
  3. v14remove Order.total — blockedBREAKING
  4. v14add Order.totalAmountSAFE
  5. v15drop Order.total — usage clearedDANGEROUS

Know what breaks before your users do.

Publish the operations each client uses, validate proposed schemas against the environment you plan to update, and merge with the answer in hand.

Start for freeRead client registry docs