Release Train

---
name: release-train
description: Cadenced release process — weekly cut on Friday, staging Monday, canary Wednesday, 100% Friday next. Different from release-on-demand. Use when shipping multiple PRs together with predictable timing.
when_to_use: Project is on weekly/bi-weekly release cadence. User says "cut a release", "release train", "RC build", "promote to prod".
allowed-tools: Read, Glob, Grep, Edit, Write, Bash, TodoWrite
model: sonnet
disable-model-invocation: true
---

# Release Train

Cadenced releases instead of release-on-demand. Predictable timing → easier coordination across teams.

## Schedule template

```
Week N:
  Friday 17:00 → cut release/X.Y branch from main
                  (everything merged to main before this goes; everything after waits for X.Y+1)

Week N+1:
  Monday    → deploy release/X.Y to staging
  Tuesday   → soak in staging; smoke tests; manual QA
  Wednesday → canary deploy to prod (1% via slo.yml progressive_deploy)
  Thursday  → ramp 10% → 50%
  Friday    → 100%; close release/X.Y; tag v X.Y.0

Hotfixes mid-cycle:
  - Cherry-pick to release/X.Y branch only (not main)
  - Patch bump (X.Y.1); deploy out-of-band
```

## Process

### Cutting a release (Friday 17:00)

```bash
# 1. Verify main is green
gh run list --branch=main --limit=5

# 2. Determine version (semver based on Conventional Commits since last release)
next=$(npx release-please --token=$GITHUB_TOKEN --release-as=auto --dry-run | jq -r .nextVersion)
# OR for monorepo: process release-please-manifest.json

# 3. Cut branch
git checkout main
git pull
git checkout -b "release/$next"
git push -u origin "release/$next"

# 4. Open release PR (CHANGELOG generated by release-please)
gh pr create --base "release/$next" --head main --title "release: $next" --body "@release-please:auto"
```

### Promoting through environments

```bash
# Monday: deploy to staging — via YOUR BYO deploy workflow (the harness ships no
# deploy.yml; wire your platform per docs/DEPLOY-INTEGRATION.md, then substitute it here)
gh workflow run <your-deploy-workflow>.yml --ref "release/$next" -F environment=staging

# Wednesday: canary in prod (after staging soak) — requires DEPLOY_WIRED=true,
# otherwise canary-deploy.yml refuses to run (fail-closed stub)
gh workflow run canary-deploy.yml -F service=<svc> -F sha=$(git rev-parse "release/$next")

# Friday: 100% — again via your BYO workflow
gh workflow run <your-deploy-workflow>.yml --ref "release/$next" -F environment=production
git tag "v$next"
git push --tags
```

### Hotfix cycle

```bash
# Hotfix branch off the release branch
git checkout "release/$current"
git checkout -b "hotfix/$ticket"
# ... make the fix, write tests
gh pr create --base "release/$current" --head "hotfix/$ticket"
# Merge → patch bump → deploy

# Also cherry-pick to main
git checkout main
git cherry-pick <hotfix-sha>
gh pr create --base main
```

## Branch ruleset (.github/rulesets/release-branches.json)

`release/*` and `hotfix/*` branches require:
- 1 approval (relaxed; engineers can self-approve hotfixes if necessary in emergencies)
- All required status checks
- Linear history
- Signed commits
- Block force-push EXCEPT for release-please's auto-commits

## Hard rules

- **Cut at a predictable time.** Friday 17:00 every week. Don't slip without announcement.
- **Hotfixes go to the release branch first, then main.** Not the reverse.
- **No new features on release/*.** Only fixes. Features wait for the next cut.
- **The CHANGELOG is the source of truth** for what's in a release. release-please owns it.
- **Tag immediately at 100%.** `v X.Y.0` immutable; never re-tag.

## References

- release-please: https://github.com/googleapis/release-please
- Conventional Commits: https://www.conventionalcommits.org/
- Trunk-based development with release branches: https://trunkbaseddevelopment.com/release-from-trunk/