EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/docs/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
Tags
Assign human-readable names to graph artifacts for environment promotion
Overview
A tag is a human-readable alias that points to a specific graph artifact. Instead of referencing an artifact by its SHA-256 digest (@sha256:6c3c62...), you assign a named tag, like staging or production, and use that name in your router configuration:
1APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph:production"Tags decouple your router configuration from specific artifact digests. To promote a schema to the next environment, reassign the tag to point to the new artifact. Routers referencing that tag pick up the change automatically. No configuration update or redeploy is required.
Apollo-managed and user-managed tags
Tags come in two kinds: those managed by Apollo and those you manage yourself.
Apollo-managed tags
GraphOS automatically creates one tag per graph variant. This tag always points to the most recently published artifact for that variant and is updated on every successful schema publish. Apollo-managed tags can't be deleted or reassigned.
For example, for a variant named current, GraphOS maintains a tag like current-97b0560280ed60a5. The variant name is normalized to be OCI-compatible by removing unsupported characters and appending a 16-character SHA-256 hash to preserve uniqueness.
User-managed tags
You create user-managed tags using the Rover CLI command rover graph-artifact tag. These tags can point to any artifact—you can reassign them (to promote a schema) or delete them at any time. Use user-managed tags to build environment promotion workflows.
Promote schemas across environments
Tags are the recommended way to promote a schema from one environment to another. Configure each environment's router to reference a tag rather than a digest, then reassign the tag when you're ready to promote.
1# Staging router — references the 'staging' tag
2APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph:staging"
3
4# Production router — references the 'production' tag
5APOLLO_GRAPH_ARTIFACT_REFERENCE="artifact.api.apollographql.com/my-graph:production"With this setup, your router configurations never change. When you're ready to promote:
Publish a schema. GraphOS creates a new graph artifact with a SHA-256 digest.
Assign the staging tag to the new artifact.
Validate. Run tests against the staging router.
Promote. Reassign the production tag to the same artifact.
Roll back if needed. Reassign the production tag to the previous artifact.
To manage tags, use the Rover CLI. See the Rover graph-artifact command reference.
Promote using digest references
If you aren't using tags, you can still promote by updating the APOLLO_GRAPH_ARTIFACT_REFERENCE in each environment's router configuration and redeploying.
Publish a schema. GraphOS creates a new graph artifact.
Copy the artifact's reference URI from the Launches page in Studio.
Pin the staging router to the new artifact and redeploy.
Run tests against staging.
If tests pass, update the production router to the same artifact reference and redeploy.
If an issue arises, revert the production router to the previous artifact reference and redeploy.
Limits
GraphOS enforces limits on the number of tags per artifact and per graph. If you reach the limit of 1000 tags, rover graph-artifact tag returns an error. Use rover graph-artifact untag to remove unused tags and stay within limits.