Graph Artifacts

Every publish creates a versioned package of your supergraph schema

Requires ≥ Router v2.7.0

Overview

Graph artifacts are versioned, immutable packages of your supergraph schema.

Each time you publish a schema, GraphOS automatically generates a graph artifact. GraphOS stores each artifact in the GraphOS registry and identifies it by a unique SHA-256 digest. You can reference that digest in your router configuration so your router runs that schema version.

Graph artifacts are immutable: they represent the same schema version that GraphOS created at the time of publication, and their SHA digest never changes. By contrast, when you configure a router with a graph ref—for example, my-graph@production—it always resolves to the latest schema for that variant.

When to use graph artifacts

Use graph artifacts for production deployments. Because graph artifacts are immutable and require an explicit restart or redeploy to take effect, your infrastructure team retains full control over when schema changes go live.

Use graph artifacts if you:

  • Manage multiple environments, like staging and production

  • Need to control exactly when your router picks up schema changes

  • Want to audit what schema was live at a given time

Apollo Router also supports hot-reloading schemas, where schema changes take effect automatically without a restart. Hot-reloading can be convenient for development, but in production, schema updates happen beyond the control of your infrastructure team and reloads temporarily increase CPU usage, request latency, and memory footprint. For production environments, use graph artifacts instead.

Limitations

  • Graph artifacts are only available for supergraphs using managed federation with Apollo Router v2.7 or later.

  • Graph artifact digest references do not hot reload; restart or redeploy the router to switch versions.

  • Graph artifact tag references can hot reload with Apollo Router v2.11.0 or later.

  • The Rover CLI doesn't yet support querying for graph artifact details.

Usage

Run a graph artifact

After publishing a schema, find its graph artifact on the Launches page in GraphOS Studio:

Select the Copy button to copy the graph artifact's reference URI.

To configure the router with this graph artifact, set the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable, or use the --graph-artifact-reference command-line argument.

Bash
1# Instead of pointing your router to a graph ref:
2# APOLLO_GRAPH_REF=my-graph@production
3
4# As an environment variable:
5APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph@sha256:6c3c62..."
6
7# As a command-line argument:
8./router --graph-artifact-reference="artifact.api.apollographql.com/my-graph@sha256:6c3c62..."

With that setting, your router runs that schema version until you update it to a new graph artifact.

tip
Make sure to restart or redeploy your router so it runs the newly configured graph artifact.

Roll back to a previous version

If a new schema version causes issues, roll back by pointing your router to a previous graph artifact. From the Launches page in Studio, copy the reference URI of the last known-good artifact and use it to set the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable. (You can also use the --graph-artifact-reference command-line argument.)

After restarting or redeploying, your router runs the stable schema of that graph artifact.

Move a graph artifact from staging to production

  1. Publish a schema. GraphOS automatically creates a new graph artifact.

  2. Pin the staging router to the new artifact.

  3. Run tests against staging.

  4. If the tests are successful, update the production router to use the same artifact.

  5. If an issue arises, roll back production by switching to the previous artifact reference.

Best practices

Graph artifacts give you fine-grained control over schema rollouts. To use them effectively:

  • Promote through environments: Pin new artifacts in staging first, validate them, then promote them to production.

  • Keep a rollback plan: Record the reference URI of your last known-good artifact.

  • Audit often: Use the Launches page in Studio to confirm which artifact each environment is running.

  • Automate with CI/CD: Integrate artifact publishing and promotion into your pipelines for repeatable deployments.