Skip to content

Deploy with the GraphOps CLI

Build your Subgraph and create or update its Managed Subgraph in one command, then release each new version from your terminal or CI.

Go from your Subgraph project to an indexing Managed Subgraph with one command. graphops subgraphs deploy runs your project's Graph CLI to build and upload the Subgraph, then creates the Managed Subgraph or stages the build as its Next version. A new version serves queries only when you promote it.

Prerequisites

  • A Subgraph project with subgraph.yaml and Graph CLI in its dependencies.
  • The GraphOps CLI, signed in to your organization.
  • A monthly plan with room for another Managed Subgraph. Managed indexing accrues charges while a version is indexed, whether or not it receives queries.

Create the Managed Subgraph

Deploy with --create

Run the deploy from your project. The name you pass names the Managed Subgraph, and Graph CLI uses it as the Subgraph name. --create is required the first time, because indexing and its charges start when the Managed Subgraph is created. Without it, the CLI stops before building when no Managed Subgraph has that name.

CLI · GraphOps CLI

# Run from your Subgraph project. Builds with your graph-cli and creates the Managed Subgraph.
graphops subgraphs deploy my-subgraph --create

Graph CLI's build output appears as usual. Graph CLI deploys through a local GraphOps bridge, so the Graph node address it prints is on 127.0.0.1. The CLI then prints the Deployment CID, the network, the query URL and a link to the Managed Subgraph in GraphOps Platform. A Managed Subgraph indexes one network: to index the same Subgraph on another network, deploy it under another name, for example with the network in the name.

Wait for it to sync

CLI · GraphOps CLI

# Wait until the current version has caught up with the network (default timeout 30m).
graphops subgraphs wait my-subgraph --for synced
graphops subgraphs status my-subgraph

--for synced waits until the Current version has caught up with the network. The wait gives up after 30 minutes by default, exiting with code 6; indexing continues, so wait again or check graphops subgraphs status. The wait stops at once with code 5 if the deployment reports a failure, or if the Managed Subgraph is suspended or being deleted. When the organization's credits run out, the error code is credits_exhausted: add credits to resume indexing.

Query it

Query the Managed Subgraph through an Endpoint Alias or its Deployment CID with an API key that includes Subgraphs. graphops subgraphs status prints the query URL of the Current version's Deployment CID. See Query a Subgraph.

Release a new version

Deploy again from the same project. The CLI stages the build as the Next version while the Current version keeps serving. 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

Each version you stage indexes from its start block and accrues charges alongside Current, so check that your credit balance covers both during the upgrade.

The deploy stops instead of staging in two cases:

  • 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.
  • Another Next version is already staged. Deploy with --replace-next to cancel it and stage the new build, or remove it with graphops subgraphs unstage my-subgraph.

When the Next version can be promoted, promote it. It becomes Current, and Endpoint Aliases that target the Managed Subgraph serve it. 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.

CLI · GraphOps CLI

graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph

Develop and release a Subgraph explains when a Next version becomes promotable and how promotion affects your Endpoint Aliases.

Roll back

Find the Deployment CID of the release you want to return to with graphops subgraphs history my-subgraph, which lists the Next, Current and previous versions, newest first; graphops subgraphs status shows the most recent previous version. Deploy that CID with --cid, which stages it as Next without building, then promote it. The staged version indexes again from its start block, so it becomes promotable only once it has caught up, and it accrues charges alongside Current until then.

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>

Deploy a build made elsewhere

--cid works for any Deployment CID, so you can build in one place and release from another. For example, run graph build --ipfs in a CI build job, then graphops subgraphs deploy my-subgraph --cid <Deployment CID> in a release job. The outcome, the flags and the permissions are the same as when the CLI builds.

To manage a Subgraph you already deployed elsewhere, add --create to create its Managed Subgraph from the CID. To follow the versions published to a Graph Network Subgraph ID instead, run graphops subgraphs create my-subgraph --subgraph-id <Graph Network Subgraph ID>. See Connect an existing Subgraph to choose between them.

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.

CLI · GraphOps CLI

# GRAPHOPS_TOKEN holds a service account API key from your CI system's secrets.
graphops subgraphs deploy my-subgraph
graphops subgraphs wait my-subgraph --for promotable --timeout 2h
graphops subgraphs promote my-subgraph

To promote exactly the build the job staged, read deploymentCid from graphops -o json subgraphs deploy and pass it 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.

CommandPermissions
list, status, history, waitRead Managed Subgraphs (managedSubgraphs.read)
deploy a new versionRead Managed Subgraphs and Stage deployments (managedSubgraphs.stage)
deploy --replace-nextRead Managed Subgraphs, Stage deployments and Cancel Next (managedSubgraphs.unstage)
unstageRead Managed Subgraphs and Cancel Next
promoteRead Managed Subgraphs and Promote Next (managedSubgraphs.promote)
deploy --create, createRead 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.

Next steps

Last updated