OCI Registry

Pull and inspect graph artifacts using OCI-compliant tools

Requires ≥ Router v2.7.0

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. You can use standard OCI tools to pull graph artifacts from the GraphOS registry and inspect their contents.

tip
If you need to run without connectivity to Apollo's registry—for air-gapped environments, restricted networks, or full infrastructure ownership—see the guide on self-hosting graph artifacts.

Find OCI artifact references

To programmatically retrieve a graph artifact reference, query the GraphOS Platform API. Apollo allows certain characters in the graph ID and variant name that the OCI Distribution Spec doesn't, so Apollo removes these characters and appends a hash to preserve uniqueness.

Run the following Platform API query to retrieve the OCI-compatible repository and tag mapping:

GraphQL
GraphArtifactTagLocation
1query GraphArtifactTagLocation($graphId: ID!, $variantName: String!) {
2  graphArtifactTagLocation(graphID: $graphId, variantName: $variantName) {
3    repository
4    tag
5  }
6}

Alternatively, calculate the tag mapping manually by stripping any non-alphanumeric characters (besides dot, underscore, and dash) and then calculating the SHA256 checksum. For example, the variant name current maps to:

Bash
1$ echo -n current | sha256sum | cut -c 1-16
2current-97b0560280ed60a5

Query the Platform API to retrieve the unique digest fingerprint of the latest build:

GraphQL
GetGraphArtifact
1query GetGraphArtifact($graphId: ID!, $tag: String!) {
2  graphArtifactByTag(graphID: $graphId, tag: $tag) {
3    location {
4      digest
5      uri
6    }
7  }
8}

The returned uri is a combination of the hashed graph ID and variant, and you can use that uri to directly launch a router using that supergraph.

Pull graph artifacts

You can use any OCI-compliant tool to pull graph artifacts from the GraphOS registry.

In most cases, Apollo Router can fetch the artifact directly when you configure APOLLO_KEY and APOLLO_GRAPH_ARTIFACT_REFERENCE. Pull the graph artifact manually when you need a local copy for inspection, debugging, or custom workflows.

Authenticate with the GraphOS registry

Graph artifacts are stored in an OCI-compliant registry at artifact.api.apollographql.com. Tools like ORAS and the Docker CLI use your local Docker credential store (for example, ~/.docker/config.json and any configured credential helpers) to authenticate. Before you can pull an artifact, sign in to the registry with a graph API key.

To authenticate with the GraphOS registry using ORAS:

Bash
1oras login artifact.api.apollographql.com
2# When prompted, enter any non-empty username.
3# Use your Graph API key as the password.

To authenticate with the GraphOS registry using Docker:

Bash
1export APOLLO_KEY="service:YOUR_GRAPH_API_KEY"
2echo "$APOLLO_KEY" | docker login artifact.api.apollographql.com --username token --password-stdin

After signing in, your credentials are saved to the Docker authentication configuration, which ORAS and Docker both use when pulling artifacts.

To pull a graph artifact using ORAS:

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

To pull a graph artifact using Docker:

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

Inspect graph artifacts

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:

Bash
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:

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