8. Making changes to the supergraph

Part 2: Safe API delivery

📋 Process of making changes to the supergraph

  1. Run schema checks.

  2. Deploy code changes.

  3. Publish the new to .

The steps above in diagram form

📋 Step 1: Schema checks

Schema checks are a set of predefined tests that help identify potential failures caused by updates. They check for issues like incompatibilities between schemas or breaking existing client s. With , we can ensure that our schema changes won't cause issues when we deploy to production.

Types of :

  • Build checks validate that a 's changes can still compose successfully with other subgraph schemas in the .
  • Operation checks validate that a 's changes won't break any s that existing clients send to the graph.
  • Linter checks analyze your proposed changes for violations of formatting rules and other GraphQL best practices. You can see the full list of default rules in the Apollo documentation.

rover subgraph check

Using the CLI, we can run locally in our terminal or we can integrate schema checks into our CI pipelines to run automatically against new pull requests.

rover subgraph check <GRAPH_REF> \
--schema <SCHEMA_FILE_PATH> \

Note: The GRAPH_REF refers to the graph reference, which identifies our in . A graph ref starts with the graph's ID, followed by an @ symbol, followed by the graph .

This command first runs a build check, then an check, then a linter check, and finally outputs the results in the command line. It also reports the results to Studio, so we can view them from our graph's Checks page.

📋 Step 2: Deploy code changes

This step looks different for all projects. In this workshop, we've set up automatic deploys to Railway (or your hosting platform of choice) when new commits are pushed to the main branch on GitHub.

📋 Step 3: Publishing the subgraph schema

The needs to know about our schema updates! To do so, we need to publish our schema to the registry.

rover subgraph publish

Similar to , there are two main ways to publish a schema using the CLI: locally, or in CI pipelines.

rover subgraph publish <GRAPH_REF> \
--schema <SCHEMA_FILE_PATH> \

GraphOS launch

A launch represents the complete process of applying a set of updates to a . A launch is triggered when a new or updated version of a is published, when a new subgraph is added, or when the configuration is changed.

Expand section below to see full image description