Build your Subgraph through as many versions as you need while your production application keeps serving the version you released. You test each candidate through its own Deployment CID, and your application moves only when you promote a candidate that is indexed and ready.
This guide uses one Managed Subgraph as your release pipeline: its Current version serves production, and its Next version is the candidate you are testing. Each step shows the GraphOps CLI command and the GraphOps Platform action that do the same thing; use whichever fits your workflow.
Prerequisites
- A Managed Subgraph with a Deployment CID target, so each release waits for your approval. Deploy your own Subgraph creates one.
- The owner or developer role, and the requirements to start indexing: available credits, room in your plan, and a supported network.
- A query key that includes Subgraphs.
Managed indexing accrues charges while a version is indexed, whether or not it receives queries. Each version you stage indexes from its start block and accrues charges alongside Current, so check that your credit balance covers both during an upgrade.
Set up your Endpoint Aliases once
Create the production Endpoint Alias
Create an Endpoint Alias named for your application, such as orders, with a
Managed Subgraph target and the Current version behavior. It moves to each
version you promote. With the GraphOps CLI, run
graphops subgraphs endpoint-aliases create orders --managed-subgraph my-subgraph; in GraphOps
Platform, add it in the last step of creating the Managed Subgraph. Configure your production
application with its URL:
Reference
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>
Optionally, create a staging Endpoint Alias
If your development or staging environment should keep one URL across candidates, create a second
Endpoint Alias, such as orders-staging, with the same Managed Subgraph target and the Next version
behavior (--behavior next). It serves each candidate as soon as it can answer queries, and falls
back to Current between releases.
Endpoint Aliases explains each
behavior.
Test a new version
Stage the change as the Next version, then query it while it indexes. Your production Endpoint Alias keeps serving Current throughout.
With the GraphOps CLI, deploy again from the same project. The CLI builds, uploads and stages the build as Next. Deploying a build that is already Current or Next changes nothing.
CLI · GraphOps CLI
# Stages the new build as the Next version. The Current version keeps serving.
graphops subgraphs deploy my-subgraph
The deploy prints the Next version's query URL for testing. It stops instead of staging in these cases:
- A Next version is already staged. The CLI stops before building, because it can't know the new
build's Deployment CID until Graph CLI uploads it. If the staged version is the one you want,
wait for it and promote it. Otherwise deploy with
--replace-nextto cancel it and stage the new build, or remove it withgraphops subgraphs unstage my-subgraph. With--replace-next, a build of the staged Deployment CID itself changes nothing. - Graph CLI's
--networknames another network than the Managed Subgraph's. The CLI stops before building. Without--network, GraphOps refuses the uploaded build instead. - The new schema is not compatible with Current. The CLI lists the issues. Check the queries your
application sends, then deploy again with
--accept-schema-changes.
From GraphOps Platform, build and upload with Graph CLI as in Deploy from GraphOps Platform, then:
- On the Managed Subgraph, choose Start upgrade and enter the new CID. GraphOps checks it as you enter it. Continue once it passes, then review the schema comparison, which lists changes that can break your existing queries.
- If you find a problem, choose Cancel upgrade, deploy a fix and stage the new CID. A Managed Subgraph has one Next version at a time.
Query the candidate through its Deployment CID endpoint or your staging Endpoint Alias. Check
_meta.block.number to see how far it has indexed. Results are incomplete until it catches up.
Release the version
- Update and deploy any clients affected by schema changes before you release.
- Wait until Next can be promoted: healthy and close to the network head. GraphOps Platform shows
Ready to promote, and
graphops subgraphs wait --for promotablereturns. - Promote it with
graphops subgraphs promote, or choose Promote version. Next becomes Current, and your production Endpoint Alias moves to it while your application keeps the same URL. The CLI names the Endpoint Aliases that now serve it. - Query
_meta.deploymentthrough the production Endpoint Alias to confirm the CID it serves.
CLI · GraphOps CLI
graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph
If GraphOps refuses the promotion, for example because the Next version has not caught up or you
lack the permission, the CLI prints the reason and exits with code 5. The previous version is
removed after promotion, so its Deployment CID query URL stops working. Record each released
Deployment CID.
Roll back
Returning to a previous version is another upgrade, not an instant switch. Stage the previous Deployment CID as Next, let it index, and promote it when it is ready. Plan for that indexing time in your release process, and fix forward when a corrected version would be ready sooner.
With the GraphOps CLI, graphops subgraphs history my-subgraph lists the Next, Current and previous
versions, newest first. Deploy the CID you want with --cid, which stages it as Next without
building, then promote it:
CLI · GraphOps CLI
# Find the Deployment CID of the earlier release: Next, Current and previous versions, newest first.
graphops subgraphs history my-subgraph
# Stage it in place of any Next version. It indexes again from its start block.
graphops subgraphs deploy my-subgraph --cid <PREVIOUS_DEPLOYMENT_CID> --replace-next
graphops subgraphs wait my-subgraph --for promotable
graphops subgraphs promote my-subgraph --expect-next <PREVIOUS_DEPLOYMENT_CID>
In GraphOps Platform, choose Start upgrade and enter the previous CID.
Release from CI
Run the same commands in CI as a service account. Set
GRAPHOPS_TOKEN to one of its service account API keys, stored as a secret of your CI system.
Install an exact CLI version in CI, as Run the CLI in CI
shows, so a new release can't change the JSON your job reads.
CLI · GraphOps CLI
# GRAPHOPS_TOKEN holds a service account API key from your CI system's secrets.
# --replace-next replaces any staged Next version, even one someone else staged: drop it when
# several pipelines release the same Managed Subgraph.
result=$(graphops -o json subgraphs deploy my-subgraph --replace-next)
CID=$(printf '%s' "$result" | jq -r .deploymentCid)
case $(printf '%s' "$result" | jq -r .outcome) in
staged | replaced | already_staged)
graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph --expect-next "$CID"
;;
# already_current (and created, with --create): the build already serves; nothing to promote.
esac
The job reads the outcome of graphops -o json subgraphs deploy to decide what comes next, so
running it again for the same build succeeds:
outcome | Meaning | Next step |
|---|---|---|
created | --create created the Managed Subgraph from the build | None: it is Current. Wait with --for synced if the job needs it ready. |
staged | The build is the Next version | Wait with --for promotable, then promote |
replaced | --replace-next cancelled the previous Next version and staged the build | Wait with --for promotable, then promote |
already_current | The build is already Current | None |
already_staged | The build is already the Next version | Wait with --for promotable, then promote |
To promote exactly the build the job staged, pass the deploy's deploymentCid to
graphops subgraphs promote --expect-next. The promotion then stops with code 5 and
next_changed if another version was staged meanwhile.
The service account needs these permissions. CLI messages name them by ID.
| Command | Permissions |
|---|---|
list, status, history, wait | Read Managed Subgraphs (managedSubgraphs.read) |
deploy a new version | Read Managed Subgraphs and Stage deployments (managedSubgraphs.stage) |
deploy --replace-next | Read Managed Subgraphs, Stage deployments and Cancel Next (managedSubgraphs.unstage) |
unstage | Read Managed Subgraphs and Cancel Next |
promote | Read Managed Subgraphs and Promote Next (managedSubgraphs.promote). With Read Endpoint Aliases (endpointAliases.read) it also names the Endpoint Aliases now serving the new version; without it, it warns and still succeeds. |
deploy --create, create | Read Managed Subgraphs and Create Managed Subgraphs (managedSubgraphs.create), plus Reconfigure Managed Subgraphs (managedSubgraphs.reconfigure) to follow a Graph Network Subgraph ID |
A permission limited to named Managed Subgraphs works only on those. Creating a Managed Subgraph acts on the whole organization, so a service account that creates one needs these permissions without a limit.
Keep a separate development environment
One Managed Subgraph is enough when you test one candidate at a time. Create a second Managed Subgraph for development when you need a development version that keeps running, such as for a long-lived staging environment, while production upgrades separately:
- Point your development Endpoint Alias at the development Managed Subgraph with a Managed Subgraph target, and promote there as often as you like.
- To release, stage the tested Deployment CID on the production Managed Subgraph and promote it when it is ready.
Each Managed Subgraph uses its own plan slot and accrues its own indexing charges, even when both index the same Deployment CID.
Release by publishing on The Graph Network
If your team publishes the Subgraph on The Graph Network, you can make that publication the release. Create the production Managed Subgraph with a Graph Network Subgraph ID target for your Subgraph's ID. Each version you publish becomes Next and is promoted automatically when it is ready, including breaking schema changes.
Because publishing releases the version, test each candidate before you publish it, for example in
a development Managed Subgraph with a Deployment CID target. Point your
production application at an Endpoint Alias that targets the production Managed Subgraph, not at
the subgraphId endpoint, which moves to each publication before it is indexed.
Before production
- Point production clients at an Endpoint Alias, never at a candidate's Deployment CID.
- Keep a record of each released Deployment CID and the schema your clients expect.
- Log
_meta.deploymentwith production queries so you can tell which version served a request. - Check that your credit balance covers both versions during an upgrade. See Plan indexing costs.
Next steps
Last updated
Deploy your own Subgraph
Take your Subgraph project to an indexed Managed Subgraph, with one GraphOps CLI command or with Graph CLI and GraphOps Platform.
Manage Endpoint Aliases
Keep a stable query URL by targeting a Deployment CID, a Managed Subgraph, or a Graph Network Subgraph ID, and choose which version it serves.