Release Runbook

This page documents the end-to-end release process, including the normal flow, key decision points, and links to recovery procedures for common failure scenarios. For detailed troubleshooting steps, see Release Issues.

Release Timeline

Each release follows a two-week sprint cycle:

Day	Event	Workflow	Details
Sprint Day 1 (Wednesday)	Release branch cut	new_release_branch.yml	Creates release/vX.X.X branch from develop, tags RC-vX.X.X-MMDDYY-HHMM
Sprint Day 1 (Wednesday)	RC build	release_candidate_build.yml	Triggered by RC tag. Builds iOS (TestFlight) and Android (Firebase) staging builds for QA
Sprint Day 1 (Wednesday)	Release ticket created	release_branch_issue.yml	Triggered by branch creation. Creates GitHub issue, TestRail milestone, Slack coordination thread
Sprint Days 1-3 (Wed-Fri)	QA regression testing	Manual	QA tests the RC build and approves via the release-qa environment gate
Sprint Days 3-5 (Fri-Mon)	Product approval	Manual	Product owner approves via the release environment gate
After both approvals	Release PR + tag	run_approval.yml / release_pull_request.yml	Merges release to main (squash), tags vX.X.X, creates PR to merge back to develop
After tagging	Release build	release_build.yml	Triggered by vX.X.X tag. Builds production iOS (App Store review) and Android (Pre-Prod Stash)
Sprint Day 14 (Tuesday)	Go Live	go_live.yml	Promotes iOS from App Store Connect and Android from Pre-Prod Stash to production

Workflow Chain

new_release_branch.yml
  └─ release_branch.sh
       ├─ Creates release/vX.X.X branch
       └─ Tags RC-vX.X.X-MMDDYY-HHMM
            │
            ├──► release_candidate_build.yml (triggered by RC tag)
            │      ├─ build_ios.yml (lane: rc)
            │      └─ build_android.yml (lane: rc)
            │
            └──► release_branch_issue.yml (triggered by branch creation)
                   ├─ Creates release ticket
                   ├─ Creates TestRail milestone + test run
                   ├─ Posts Slack coordination thread
                   ├─ QA approval gate (environment: release-qa)
                   └─ Release approval gate (environment: release)
                          │
                          └──► run_approval.yml
                                 └─ release_pull_request.yml
                                      ├─ Merges release → main (squash)
                                      ├─ Tags vX.X.X
                                      │     └──► release_build.yml (triggered by tag)
                                      │            ├─ build_ios.yml (lane: review)
                                      │            └─ build_android.yml (lane: review)
                                      └─ Creates PR: release → develop

go_live.yml (every Tuesday at 12:00 UTC)
  ├─ build_ios.yml (lane: release) — promotes from App Store Connect
  └─ build_android.yml (lane: release) — promotes from Pre-Prod Stash

Normal Release Checklist

Before release branch cut

• All intended work is merged to develop
• Daily QA builds are passing

After release branch cut (Sprint Day 1)

• RC build completed successfully (check Slack for build thread)
• Release ticket created in GitHub with correct version number
• TestRail milestone and test run created
• What's New content prepared (App Store and optional in-app)

During QA (Sprint Days 1-5)

• QA regression testing completed on RC build
• Any required fixes cherry-picked to release branch (see Adding code to release)
• QA approval given via release-qa environment gate
• Product approval given via release environment gate

After approval

• Release PR merged to main automatically
• vX.X.X tag created and pushed
• Release build completed for both platforms
• iOS build submitted to App Store for review
• Android build uploaded to Pre-Prod Stash track
• PR to merge release changes back to develop created and merged

Go Live (Sprint Day 14, Tuesday)

• App Store review approved (check App Store Connect)
• Go Live workflow runs successfully
• Verify app is live in both stores

Decision Trees

Code needs to go into the release branch

A build failed

Need an off-cadence release

Key Workflows Reference

Workflow	Trigger	Manual Dispatch?	What It Does
new_release_branch	Schedule (Wed)	Yes	Cuts release branch, tags RC
release_candidate_build	RC-v* tag push	No	Builds staging RC for QA
release_branch_issue	release/* branch creation	No	Creates release ticket, TestRail, Slack thread, approval gates
release_build	v* tag push	No	Builds production for App Store review
go_live	Schedule (Tue)	Yes (requires manual-release environment)	Promotes builds to production in stores
on_demand_build	Manual only	Yes	Builds any branch for testing

Important Notes

Go Live runs every Tuesday

The Go Live workflow runs every Tuesday, not just on release Tuesdays. On non-release weeks, the iOS lane will fail (no pending version) and the Android lane will exit gracefully. If a release is approved and built early, it will be promoted on the next Tuesday regardless of whether it's the intended release date.

Rebuilds are all-or-nothing

The RC build, release build, and Go Live workflows all build/promote both iOS and Android together. There is currently no way to rebuild or promote a single platform independently. Deleting and recreating a tag to re-trigger a build will rebuild both platforms.

Approval mechanisms

Release approval uses GitHub environment protection rules (release-qa and release environments), not the legacy /approve slash command. The checkboxes in the release ticket are for tracking purposes and are not connected to the automated approval gates.