---
title: "Release Cycle"
icon: "clock"
---

This page explains how code moves from merge to production and why each step exists.

## The Cycle

```
Merge to main ──→ Deploy to staging
                          │
                          Started by hand: the Cloud gate picks the tip of main, which staging must have deployed
                          │
                          E2E matrix + upgrade test on the staging image
                          │
                          One approval ──→ canary ──→ whole Cloud fleet
```

## Steps & Why

### Staging — every merge

Each merge to `main` builds a `version.sha.beta` image and deploys it to staging. The deploy checks on the commit tell the gate that the image exists.

**Why**: Every commit runs on a real deployment before Cloud gets it.

### Cloud gate — by hand

`continuous-delivery-cloud.yml` takes the tip of `main`, and stops if staging has not deployed it. It runs the E2E matrix (four configurations) and the upgrade test from the last self-hosted release on the image staging built. The run summary lists the tickets in the candidate. One approval in the `production` environment deploys the image to the canary and then to the fleet.

**Why**: Cloud gets the exact image that staging runs and the matrix tested. The gate runs by hand until the E2E suite covers more of the product; then it runs Sunday to Thursday at 8 AM UTC, so each deploy is small.

### Self-hosted

Self-hosted releases use `release-self-hosted.yml`. See [Releases](/handbook/engineering/playbooks/releases).

## Putting It Together

| Time | What Happens |
|---|---|
| Any time | Merge to `main` → staging deploy |
| When the release captain starts it | Cloud gate: checks, approval, canary, fleet |

## Overrides

- **Hotfix**: Merge the fix into `main`, then run `continuous-delivery-cloud.yml` by hand with `hotfix_prs`. Cloud gets only those PRs on top of what it runs, after the same checks and approval. The rest of `main` waits for the next full gate run.
- **Emergency**: Use `emergency-cloud-deploy.yml` to deploy directly to production, bypassing staging entirely. Use sparingly.

## FAQ

**Q: I merged at 10 AM UTC on a Wednesday. When does my code reach production?**
It deploys to staging immediately. The next Cloud gate run picks it up, and it reaches Cloud when the E2E matrix passes and the deploy is approved. Until the gate runs on a schedule, that is when the release captain starts it.
