# Catch Breaking GraphQL Schema Changes in CI

Yes. An agent adds a CI job that fails a pull request when the schema file drifts from the code or removes something clients use, and tests it on real edits.

[Run this on Rush](https://cloud.getrush.ai/run/add-schema-check-to-ci/graphql/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by finding where the schema's source of truth is and whether a printed copy exists to compare against. In a code-first server like graphql/swapi-graphql, the types are graphql-js objects under `src/schema`, and a printed copy is committed at the repository root as `schema.graphql`. Two scripts produce it: `npm run print-schema` writes `printSchema` output to the terminal and `npm run store-schema` writes the same text to the file. Nothing checks that anyone ran them. The only CI configuration is a `.travis.yml` with three settings, and the repository has no `.github/workflows` directory, so a pull request that deletes a field can merge with the committed schema still listing it.

It adds one workflow with two checks, because they catch different mistakes. The drift check regenerates the schema with `npm run store-schema` and fails if `git diff --exit-code schema.graphql` reports a difference, which means the code changed and the file was not updated. The compatibility check compares the pull request's `schema.graphql` with the base branch's copy, read with `git show`, and classifies each difference. For that the agent needs no new dependency: `package.json` pins `graphql` at 14.5.8, whose utilities include `buildSchema`, `findBreakingChanges` and `findDangerousChanges`. A short script under `scripts` prints every finding with its type and description, exits non-zero when any is breaking, and lists dangerous ones, such as a new enum value, as warnings.

The install step in this repository decides whether the job is reliable. The schema module imports the Star Wars data from `cache/data.json`, which is ignored by Git and created by the `postinstall` script: `npm run download` fetches it from an external API and `npm run build` compiles `src` with Babel. Without that file the schema cannot be imported, so printing it fails. The download script skips its work when the file already exists, so the agent caches `cache/data.json` between workflow runs and the check does not depend on a third-party API being up for every pull request. The workflow reads its Node version from `.nvmrc`, checks out with enough history to see the base branch, and asks for read-only `contents` permission.

A CI check that has never failed is unproven, so the agent makes it fail on purpose in the sandbox. After `npm install`, it runs both checks on the untouched tree and reports whether the committed file already matches the code; if it does not, regenerating it is a separate first commit. Then it makes three trial edits, each on a scratch branch it never pushes: removing a field from a type, which must be reported as breaking; adding a nullable field, which must pass; and editing a type without running `store-schema`, which must trip the drift check. It keeps the script's output for each. Jest specs under the existing `__tests__` layout feed the script pairs of small schema strings and assert the exit status and the finding types. The workflow's first real execution is on the pull request that adds it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A GitHub issue labelled ci asks for pull requests to this GraphQL server to fail when they break the schema. Read package.json, .travis.yml, .nvmrc, .gitignore, schema.graphql, scripts/print-schema.js, scripts/store-schema.js, scripts/download.js, src/api/local.js and src/schema/index.js first. Say in the pull request how schema.graphql is produced, what CI exists today, and what the schema needs at import time that is not in Git. Add one GitHub Actions workflow for pull requests with two checks. Drift: regenerate the schema with the existing npm script and fail if schema.graphql differs. Compatibility: compare the pull request's schema.graphql with the base branch's copy using buildSchema, findBreakingChanges and findDangerousChanges from the pinned graphql version, in a script under scripts; print every finding, exit non-zero on a breaking one and list dangerous ones as warnings. Add no dependency unless the pinned version lacks those functions, and say so if it does. Use the Node version from .nvmrc, fetch enough history to read the base branch, request only contents: read, and cache the downloaded data file so the job does not call the external API on every run. Leave .travis.yml in place and mention it. Run npm install and both checks on the untouched tree and report the result; if the committed schema is already out of date, regenerate it in its own commit. Then on scratch branches that you do not push, remove a field, add a nullable field, and change a type without regenerating, and paste the script output for each. Add Jest specs for the script with small schema strings. Document how to land an intentional breaking change. Open a pull request that closes the issue.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds a workflow file, a comparison script and its spec, and an npm script that runs the comparison locally. If the committed `schema.graphql` had already drifted, a first commit regenerates it and the description says which types differed. The description then explains each check in a sentence and shows the three trial edits with the script's output for each: the removed field reported as a breaking change with its type and field name, the added field passing, and the forgotten regeneration caught by the drift check.

It documents the escape hatch, since a check with no override gets disabled the first time a field has to go. An intentional breaking change lands by regenerating the schema and adding a label the workflow recognises, which turns the failure into a report listing every breaking finding in the job summary. The description also notes what the comparison cannot see: a resolver that starts returning `null` or a changed meaning behind an unchanged type are behaviour, not schema.

Since the workflow runs on its own pull request, the checks on that pull request are its first results, and a run whose checks did not pass is not reported as completed. A reviewer confirms the base-branch name in the workflow matches the repository's default, reads the cache key for the data file, and decides whether `.travis.yml` should be removed in a follow-up.

## Run it on every GitHub issue labelled ci

Every GraphQL service in an org needs this once. If each has its own Project, add an automation to each with a `github` trigger on `issues.labeled`, the label `ci`, and a saved prompt that describes the two checks without naming files: find how the schema is printed, add the drift and compatibility checks, prove both fail on trial edits, and document the override. The labelled issue follows the prompt, so it can carry service-specific notes such as a schema that is written by hand in SDL.

To cover many repositories in one sweep, send this body to `POST /o/{org}/sessions` once per repository from a script. Give each call a `request_id` that is a UUID v5 of the repository's full name so a rerun of the script starts nothing twice. A key runs up to its `max_concurrent` runs at a time and the others wait as `queued`, and with a `webhook_url` on the key, Rush posts to it when each of those runs finishes, with the run's `session_url`.

## Why run it on Rush?

The script that classifies schema changes is easy to write and easy to get subtly wrong: comparing the wrong pair of files, treating a warning as a failure, passing because the schema failed to load. The way to know is to feed it real edits. In its sandbox the agent installs the project, edits actual types in `src/schema`, regenerates the file and runs the checks, three times over, and keeps each output in the run's record. The pull request shows the check failing when it should and passing when it should.

The install step is the other reason. This project downloads data and compiles itself during `npm install`, and the schema cannot be printed until both have happened. An agent working in a fresh sandbox meets that requirement the same way a CI runner will, so the caching and ordering in the workflow come from having hit the problem, not from guessing at it. The trial branches stay in the sandbox and are discarded with it.

## Frequently asked questions

### Do I need GraphQL Inspector, Apollo Studio or a schema registry for this?

No. graphql-js ships the comparison functions, and a committed schema file gives them something to compare. A registry adds client usage data, which tells you whether a removed field was in use. If you already have one, name it in the issue and the agent wires the check to it.

### Our schema is written in SDL files, not in code. Does this still apply?

Yes, and it is simpler. There is no drift check because the files are the source, so the workflow only compares the pull request's SDL with the base branch's. The agent reads how your server loads its type definitions before deciding which files to compare.

### How do we ship a breaking change on purpose?

Regenerate the schema, open the pull request and add the override label described in the workflow. The job then lists the breaking findings in its summary and passes, so the decision is visible in the pull request's history.

### What counts as breaking and what as dangerous?

graphql-js decides. Removing a type or field, changing a field's type incompatibly or adding a required argument are breaking. Changes that may surprise some clients, such as a new enum value or a changed default for an argument, are dangerous: reported, not failed.

## More GraphQL jobs

- [Review Pull Requests for a GraphQL API](https://getrush.ai/run/review-pull-requests/graphql/)
- [Upgrade graphql-js in a GraphQL API](https://getrush.ai/run/upgrade-graphql-js/graphql/)
- [Add Query Depth Limits to a GraphQL API](https://getrush.ai/run/add-query-depth-limit/graphql/)

## More jobs like this: Turn a Linear label into a PR

- [Add Custom Search Attributes to Temporal Workflows](https://getrush.ai/run/add-search-attributes/temporal/)
- [Add Search to an Eleventy Blog from a Linear Issue](https://getrush.ai/run/add-search/eleventy/)
- [Add Search to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-search/gatsby/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
