Graph Artifacts

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 reference this digest in your router configuration, and your router runs that schema version.

Graph artifacts are immutable: they represent the same schema version that GraphOS created at publish time, and their SHA digest never changes. In 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 if you:

• Manage multiple environments such as staging and production

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

• Need to audit which schema was live at a given time

Continue using graph refs if you have a straightforward setup with one environment and you're comfortable with your router always running the latest schema.

Limitations for public preview

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

• Apollo Router cannot hot reload graph artifacts; you must restart or redeploy to switch versions.

• Apollo Router can only run graph artifacts stored in the GraphOS registry.

• The Rover CLI does not 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:

Click 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.

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 this setting, your router runs that schema version until you update it to a new 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 set the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable or 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 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, then promote 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.

Deploy with graph artifacts

Deploy with your CI/CD pipeline

You can integrate graph artifacts with your CI/CD workflow. In your pipeline, programmatically fetch the latest graph artifact's reference URI using the GraphOS Platform API. Then, save it to your router's configuration as part of deployment.

1. Fetch the graph artifact history of a variant using the GraphOS Platform API.

   GraphQL

   GetGraphArtifactHistory

   copy

   1# Fetch the latest Graph Artifact URIs for a specific graph variant
   2query GetGraphArtifactHistory($graphId: ID!, $variantName: String!) {
   3  graph(id: $graphId) {
   4    variant(name: $variantName) {
   5      launchHistory {
   6        graphArtifact {
   7          completedAt
   8          status
   9          location {
   10            uri
   11          }
   12        }
   13      }
   14    }
   15  }
   16}

   Specify your graph ID and variant name for the query:

   JSON

   Variables

   copy

   1{
   2  "graphId": "my-graph-id",
   3  "variantName": "production"
   4}

   In the response, find the graphArtifact with the latest completedAt value and a status of GRAPH_ARTIFACT_COMPLETED. The value of its location.uri field is the most recent artifact reference. Write this URI to your router's configuration during deployment to ensure it runs that specific schema version. Example response:

   JSON

   ExampleResponse

   copy

   1{
   2  "data": {
   3    "graph": {
   4      "variant": {
   5        "launchHistory": [
   6          {
   7            "graphArtifact": {
   8              "completedAt": "2025-09-30T19:22:02.684293Z",
   9              "status": "GRAPH_ARTIFACT_COMPLETED",
   10              "location": {
   11                "uri": "artifact.api.apollographql.com/my-graph-id@sha256:157be07b693c50376853f3cfaf4abb9fa61c9996f2f10912ffa1d0e92361b461"
   12              }
   13            }
   14          },
   15          {
   16            "graphArtifact": {
   17              "completedAt": "2025-09-29T17:12:43.036755Z",
   18              "status": "GRAPH_ARTIFACT_COMPLETED",
   19              "location": {
   20                "uri": "artifact.api.apollographql.com/my-graph-id@sha256:613750b0cf4f9fed76af65cf79d7be21bb5262de65e011dc469d51755c69ed49"
   21              }
   22            }
   23          }
   24        ]
   25      }
   26    }
   27  }
   28}

2. Configure the router to run the graph artifact by setting the APOLLO_GRAPH_ARTIFACT_REFERENCE environment variable or specifying the --graph-artifact-reference router command line argument.

3. If problems arise, repeat step 2 to roll back using the reference URI of a known-good graph artifact.

Deploy with the Apollo GraphOS Operator for Kubernetes

The Apollo GraphOS Operator supports graph artifacts, allowing you to use schema versions in Kubernetes-native deployments, automatically release artifacts, and let Kubernetes handle the orchestration.

Open Container Initiative (OCI) support

Graph artifacts use the Open Container Initiative (OCI) image format, and the GraphOS registry is an OCI-compliant artifact registry. This means you can use standard OCI tools to pull graph artifacts from the GraphOS registry and inspect their contents.

Pull graph artifacts

You can use any OCI-compliant tool to pull graph artifacts from the GraphOS registry. For example, after installing the ORAS CLI, pull a graph artifact using the following command, substituting your own graph ID and artifact SHA digest:

1oras pull artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

You can also use the Docker CLI to pull graph artifacts from the GraphOS registry:

1docker pull artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

Inspect graph artifacts

You can use any OCI-compliant tool to inspect graph artifacts from the GraphOS registry. For example, after installing the ORAS CLI, inspect a graph artifact using the following command, substituting your own graph ID and artifact SHA digest:

1oras manifest fetch artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>

You can also use the Docker CLI to inspect graph artifacts from the GraphOS registry:

1docker manifest inspect artifact.api.apollographql.com/<your-graph-id>@sha256:<your-artifact-sha-digest>