# Release channels

A **release channel** is a named stream of Catalyst data plane releases. Each [region](https://docs.diagrid.io/operate/platform-operations/regions) your organization owns follows one channel, and Diagrid uses that channel to work out which release the region should run next.

Who acts on that decision depends on how you run Catalyst:

- In a **self-managed BYOC** region, you choose the channel and you install each upgrade yourself.
- In a **Dedicated Cloud** or **managed BYOC** region, Diagrid installs upgrades for you from the `stable` channel. You can pause them, for example during a change freeze.
- On **Catalyst Cloud** and **Cloud Plus**, your projects run in shared regions that Diagrid operates and upgrades. There is no channel to choose and no upgrade to pause.

## Channels

| Channel | What it carries | Recommended for |
| --- | --- | --- |
| `stable` | Releases Diagrid promotes after they have run on `candidate`. This is the default. | Production regions |
| `candidate` | Each release as soon as Diagrid publishes it, while it runs ahead of `stable`. | Staging and test regions |

## Release cadence

Every release reaches `candidate` first, once Diagrid deploys it to production. It can move to `stable` after it has run there for at least 24 hours without a rollback and passed Diagrid's test suites.

Diagrid promotes a new `stable` release about every two weeks, and a person approves each promotion. Each promotion takes the newest release that qualifies and skips the ones before it, so `stable` is usually up to two weeks behind `candidate`.

Diagrid supports the three newest `stable` lines, such as 1.136, 1.135 and 1.134, and backports fixes to each of them. A line leaves support when a newer promotion pushes it out of the three, about six weeks after it reached `stable`.

## Upgrade modes

A region's **release policy** combines its channel with a **mode**:

- `follow` (the default) upgrades the region toward the newest release on its channel.
- `hold` pauses upgrades and keeps the region on the release it runs now, until you resume them.
- `pin` keeps the region on a named version. Only Diagrid can set a pin.

A region that follows its channel moves one tested upgrade at a time. When no tested upgrade leads straight from the release you run to the newest one, the next release on offer is an intermediate one. Once that release is running, the next one becomes available.

Some things stop a region upgrading even when it follows its channel: a freeze window or pin that Diagrid has set, a release Diagrid has blocked, or no tested upgrade path from your release. The CLI and the API report a reason code that says which one applies, such as `ALREADY_AT_DESTINATION` or `FREEZE_WINDOW_ACTIVE`.

Switching to a channel whose newest release is older than the one you run never downgrades the region. It stays on its release until the new channel catches up.

## What you control by region type

| | Self-managed BYOC | Dedicated Cloud and managed BYOC | Catalyst Cloud and Cloud Plus |
| --- | --- | --- | --- |
| Channel | `stable` or `candidate`, your choice | Always `stable` | Set by Diagrid |
| Who installs upgrades | You | Diagrid | Diagrid |
| What you can change | Channel, pause and resume | Pause and resume | Nothing |

## Self-managed regions

Diagrid tells you when a new release is waiting for a self-managed region, and you decide when to install it. Changing the channel only changes which releases the region is offered.

### View the channel and upgrades in the console

1. In the Catalyst console, open **Regions**. A region with an upgrade waiting shows an arrow next to its Catalyst version. Hover over the arrow to see the release on offer.

   ![Regions list with a self-hosted region on 1.134.0 and a green arrow next to the version, whose tooltip reads "Catalyst upgrade available - 1.135.0"](https://docs.diagrid.io/img/catalyst/region-upgrade-available.png)

2. Open the region. Its details show the **Release channel** and the newest release on that channel. When an upgrade is waiting, a banner at the top of the page names the release to install.

3. To switch channel, select the edit icon next to **Release channel**, or open the region's action menu (three dots) and select **Change release channel**.

4. Choose **Stable** or **Candidate**, then select **Save**.

### View and change the channel with the CLI

Show the region's policy, the release it runs, and the release waiting for it:

```bash
diagrid region release get my-region
```

The table shows the channel and mode, `currentVersion`, `nextVersion` and `upgradeReason`. An empty `nextVersion` means nothing is waiting, and `upgradeReason` says why. Add `--output json` for every field, including when a freeze window lifts.

Switch the region to another channel:

```bash
diagrid region release set-channel my-region candidate
```

You can also [pause upgrades](#pause-and-resume-upgrades) on a self-managed region. While upgrades are paused, Diagrid offers the region no new release.

:::note

Diagrid learns which release a region runs from the region itself. A region older than 1.115.0 does not report it, so `currentVersion` stays empty and no upgrade is offered. Upgrade the region to fix this.

:::

### Install an upgrade

When a release is waiting, install it with `helm upgrade` as described in [Lifecycle management](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/upgrades-operations#upgrade-and-rollback-instructions). To feed the decision into your own tooling, such as Argo CD, see [Automate upgrades](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/automate-upgrades).

## Dedicated Cloud and managed BYOC regions

Diagrid upgrades [Dedicated Cloud](https://docs.diagrid.io/operate/hosting/dedicated-cloud) and [managed BYOC](https://docs.diagrid.io/operate/hosting/byoc/managed) regions for you. These regions always follow the `stable` channel, and you cannot change it.

The one control you have is to pause upgrades, for example during a change freeze. Use the CLI to check what the region runs and what is coming:

```bash
diagrid region release get my-region
```

## Pause and resume upgrades

Pause upgrades with a reason and a review date:

```bash
diagrid region release hold my-region \
  --reason "Year-end change freeze" \
  --review-at 2027-01-05
```

- `--reason` and `--review-at` are both required.
- `--review-at` takes a date, read as midnight UTC, or an RFC 3339 timestamp such as `2027-01-05T09:00:00Z`. It must be in the future and no more than 90 days away.
- To extend a pause, run `hold` again with a new review date. The new reason and date replace the old ones.

:::warning The review date does not resume upgrades

When the review date passes, upgrades stay paused and `diagrid region release get` reports `decisionRequired` as `true`. Upgrades start again only when you resume them.

:::

Resume upgrades:

```bash
diagrid region release resume my-region
```

The region follows its channel again. If releases came out while upgrades were paused, it may move through several upgrades to catch up.

Pause and resume upgrades with the CLI or the [Control Plane API](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/automate-upgrades#read-the-decision-from-the-api). The console cannot do either.

## Next steps

- [Automate upgrades](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/automate-upgrades) of a self-managed region from the API or an in-cluster ConfigMap.
- [Lifecycle management](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/upgrades-operations) to install, upgrade and roll back a self-managed region.
- [Release notes](https://docs.diagrid.io/references/catalyst/release-notes) for what changed in each release.