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)

# 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

# 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

# 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/