Schema Checks in Continuous Integration

The Merge That Broke a Shipped App

A developer renames Post.body to Post.content for consistency. Unit tests pass, the server boots, the staging smoke test passes — staging queries were written by the same person, so of course they use the new name. The pull request merges on Friday.

The mobile build from six months ago does not. Its operations still select body, and validation rejects them the moment they arrive. Nobody can hotfix an app sitting in review queues and update cycles; the only options are to roll the rename back or to accept that every old client errors until it updates.

Nothing in the test suite was wrong. The suite simply had no access to the one input that mattered: the operations real clients have already shipped. A schema check is the pipeline stage that has it.

The check runs on the schema in the pull request, before merge, and answers three questions with the artifacts you already produce: what changed relative to the schema currently published for this graph, which registered operations stop validating against the proposal, and — when usage data is available — how many active clients each change touches. Fail the build on the answer, and Friday becomes uneventful.

The classification rules themselves are covered in the schema evolution rules topic; this topic is about the machinery that applies them on every pull request, and the release step that keeps the registry honest afterward.

What a Schema Check Actually Compares

Three inputs, three check types. Teams that understand the difference interpret failures correctly instead of just hitting "re-run."

1. Breaking-change check — proposed schema versus the published one. A structural diff classifies each edit with the rules you already know: removals, renames, required arguments, output nullability loosening, and input tightening fail; additions and deprecations pass. This check needs no client data at all, which makes it fast and also its limitation: it cannot tell you whether anyone would actually break.

2. Operation check — the proposed schema versus every registered client operation. Each checked-in operation document, persisted query, or submitted artifact is revalidated against the proposal, and the failure report names the operation, the field it lost, and the repository it came from:

FAIL  breaking-change: field "Post.body" removed
      op: GetPostSummary (mobile-app/repo, persisted id 3f9a...)
      op: nightly-digest (reports/repo, query #47)

That output changes the conversation. "The field is used by two operations in two repos" is actionable; "this is a breaking change" invites debate.

3. Usage-weighted severity — the diff joined with field-level telemetry. A removed field with zero requesting operations in 90 days reports as informational; the same removal with 40 daily requests reports as blocking. This is where the numbers from the versionless API strategy become enforcement instead of dashboards.

For federated graphs the check adds a fourth dimension: composition. The proposed subgraph SDL must still compose with its siblings into a valid supergraph, which catches errors like removing a key field an entity resolves by — a break invisible to a single-subgraph diff.

Tooling is convergent rather than exotic. Apollo Rover's graph check (and subgraph check for federation) runs all three against a graph ref; GraphQL Inspector offers diff and usage checks with a GitHub action; several gateways offer registry-hosted checks. The command surface differs, the inputs do not: proposed schema, published baseline, operation set.

The Pipeline: Check, Merge, Publish

The check only means something if it gates merges, and the registry only means something if it reflects what shipped. Both are a few lines of pipeline:

# .github/workflows/schema.yml
name: schema
on:
  pull_request:
    paths: ['schema/**']
  push:
    branches: [main]
    paths: ['schema/**']

jobs:
  check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rover
        run: curl -sSL https://rover.apollo.dev/posix/latest | sh
      - name: Breaking-change + operation check
        run: ./bin/rover graph check storefront@current --schema ./schema/storefront.graphql
        env:
          APOLLO_KEY: ${{ secrets.APOLLO_KEY }}

  publish:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rover
        run: curl -sSL https://rover.apollo.dev/posix/latest | sh
      - name: Publish the released schema
        run: ./bin/rover graph publish storefront@current --schema ./schema/storefront.graphql
        env:
          APOLLO_KEY: ${{ secrets.APOLLO_KEY }}

Design decisions hiding in that file:

• Check on pull requests, publish only on the default branch. The published schema is the baseline every future check compares against; publishing a proposal before it merges poisons the baseline with unreleased fields.
• Path filters so a schema check does not run on documentation-only pull requests, and so a release note does not trigger a publish.
• Secrets never reach forked pull requests. A fork cannot read APOLLO_KEY, so the job must degrade gracefully — report "check skipped, requires maintainer approval" rather than failing every community contribution, or run a schema-only diff that needs no credentials.
• The check is the only required status. Make it required in branch protection; an optional check is a suggestion with extra steps.

Triage when it fails. The failure names the edit, the operations, and the clients. Three legitimate resolutions:

1. Change the proposal — usually the right answer: the edit was breaking and an additive alternative exists.
2. Migrate usage first — if the removal is correct, move the listed operations to the replacement, regenerate their artifacts, and reopen the PR when the check reports zero affected operations.
3. Approve with evidence — for a genuinely intentional break (dead field with telemetry to prove it, or a coordinated release), record the evidence in the PR and let a schema owner merge. If this needs to happen often, the usage pipeline is broken, not the check.

After merge, graph publish updates the registry; gateways and other consumers fetch the new baseline from there, and the next pull request diffs against the schema that is actually live. Skipping the publish step is the quiet failure mode: checks keep comparing against an old baseline until the first false failure teaches someone the pipeline was half-wired.

Interview framing: walk the loop — propose, check against published schema and registered operations, gate, merge, publish — then explain one failure triage with a concrete example. Mentioning that deprecated-but-used fields still fail checks is the detail that shows you have operated this, not only read about it.