# Develop and release a Subgraph

Source: https://docs.graphops.xyz/subgraphs/guides/develop-and-release

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](./deploy-your-subgraph) creates one.
* The owner or developer role, and the requirements to
[start indexing](../managed-subgraphs#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-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:

```text
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

```

### Optionally, create a staging Endpoint 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](../endpoint-aliases#target-behaviors) 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.

```sh
# 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-next` to cancel it and stage the new
build, or remove it with `graphops subgraphs unstage my-subgraph`. With `--replace-next`, a build
of the staged Deployment CID itself changes nothing.
* Graph CLI's `--network` names 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](./deploy-your-subgraph#deploy-from-graphops-platform), then:

1. 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.
2. 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

1. Update and deploy any clients affected by schema changes before you release.
2. Wait until Next can be promoted: healthy and close to the network head. GraphOps Platform shows
**Ready to promote**, and `graphops subgraphs wait --for promotable`
returns.
3. 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.
4. Query `_meta.deployment` through the production Endpoint Alias to confirm the CID it serves.

```sh
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:

```sh
# 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](/platform/service-accounts). 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](/platform/cli/automation#run-the-cli-in-ci)
shows, so a new release can't change the JSON your job reads.

```sh
# 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.deployment` with 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](../managed-subgraphs#plan-indexing-costs).

## Next steps

* [Managed Subgraphs](../managed-subgraphs): See status, readiness, and costs for each version.
* [Monitor sync health](./monitor-sync-health): Detect lag and indexing errors from your application.
* [Versions](../concepts/versions): See what each setup serves while a new version indexes.