Release Management skill for Codex

A release is well run when the exact commit being shipped is tagged and reproducible, every change in it is known, it was tested as a candidate before being called final, and the rollback path was written and checked before rollout began. Publishing, tagging on the shared remote and production deploys are outward-facing: confirm each with the user.

Choose the release model

Context	Model	Branches
Continuously deployed service	Release from main; every merge (or daily batch) is a release	Tags only
Scheduled releases, one supported version	Cut release/X.Y from main at freeze; fixes land on main and are cherry-picked	release/X.Y until the next minor ships
Several supported versions (libraries, on-prem)	Maintenance branch per supported line	release/1.x, release/2.x
Mobile apps	Release branch per store submission; RC builds through TestFlight / internal track	release/X.Y

Default: release from main with tags. Introduce release branches only when you must stabilise while main keeps moving.

Before starting

• Read AGENTS.md, RELEASING.md or the release workflow in CI. Many repos automate this with release-please, changesets, semantic-release or goreleaser; follow the existing tool instead of tagging by hand.
• Confirm the version number with the user (see semantic-versioning for the bump).
• Check main is green and nothing risky is half-merged:

git fetch --tags origin
git describe --tags --abbrev=0                       # last release tag
git log --oneline $(git describe --tags --abbrev=0)..origin/main
gh run list --branch main --limit 5                  # needs network

Release checklist

- [ ] 1. Scope: list changes since last tag; flag risky ones (migrations, auth, payments)
- [ ] 2. Freeze: announce cut-off; cut release/X.Y if using branches
- [ ] 3. Bump version files and changelog in a PR
- [ ] 4. Tag release candidate vX.Y.Z-rc.1 and build artefacts from the tag
- [ ] 5. Test the RC: automated suite, smoke tests, upgrade path from previous version
- [ ] 6. Fix blockers on main, cherry-pick to release branch, tag rc.N+1
- [ ] 7. Go/no-go review against criteria (below)
- [ ] 8. Write and check the rollback plan
- [ ] 9. Tag final vX.Y.Z from the exact RC commit; publish release (confirm first)
- [ ] 10. Staged rollout with monitoring; then announce
- [ ] 11. Merge release-branch-only changes back to main; close the milestone

Cut the branch and the RC

git switch -c release/2.4 origin/main
git push -u origin release/2.4                       # confirm with user: creates shared branch

# version bump + changelog committed via PR into release/2.4, then:
git tag -a v2.4.0-rc.1 -m "Release candidate 2.4.0-rc.1"
git push origin v2.4.0-rc.1                          # confirm: CI may build and publish on tag
gh release create v2.4.0-rc.1 --prerelease --verify-tag --generate-notes

Always use annotated tags (-a): they carry author, date and message, and git describe uses them by default. Never move or re-push an existing tag: consumers and caches may already have fetched it. If a tag is wrong, make a new version.

Fixes during stabilisation

Fix on main first, then cherry-pick so the fix cannot be lost in the next release:

git switch release/2.4
git cherry-pick -x <sha-on-main>       # -x records "(cherry picked from commit ...)"

Only bug fixes for the release go onto the branch. New features wait for the next release, however small. If a fix applies only to the release branch, record that in the PR so step 11 does not miss it.

Go/no-go criteria

Agree on these before the RC, not during the meeting:

• All blocker and critical issues for the milestone closed or explicitly deferred.
• RC soaked in staging for the agreed period with no new severity-1 or 2 bugs.
• Upgrade from the previous version tested, including migrations on a copy of production-sized data.
• Rollback plan written and its first step rehearsed.
• Changelog and release notes reviewed; support and docs informed of user-visible changes.

Final tag and publish

git tag -a v2.4.0 -m "Release 2.4.0" <rc-commit-sha>   # same commit as the last RC
git push origin v2.4.0
gh release create v2.4.0 --verify-tag --notes-file RELEASE_NOTES.md --latest

The final version must be built from the same commit that passed the RC, ideally by promoting the same artefact (container digest, signed binary) rather than rebuilding.

Rollback plan

Write it before rollout. Template:

## Rollback: v2.4.0
**Trigger:** 5xx rate > 1% for 5 min, p95 > 800 ms, or any data-integrity alert
**Decision owner:** <name>; anyone may trigger during the first hour
**Steps:**
1. Halt rollout: <command or console path>
2. Redeploy previous artefact: <image digest of v2.3.2 / command>
3. Disable new flags: checkout-new-tax-engine
4. Data: migration 0042 is additive (new nullable column) - safe to leave in place
**Not reversible without restore:** <list, or "none">
**Verification after rollback:** <dashboards, smoke test command>

Rules for rollback safety:

• Schema changes in a release must be backward compatible with the previous version of the code (expand now, contract in a later release). Otherwise rollback needs a database restore, which is a different and much slower plan.
• Data backfills and irreversible jobs run after the release is confirmed healthy, not during rollout.
• Rolling forward with a patch release (see hotfix-process) is fine when it is faster, but decide that against the trigger, not by hope.

Staged rollout

Prefer canary or percentage rollouts: 1-5% for at least one traffic peak, then 25%, 50%, 100%. Mobile stores support phased release; use it. Watch error rate, latency, saturation and the business metric the release touches. Production deploys need explicit user confirmation at each stage unless they delegated the whole rollout.

Gotchas

• Tagging a commit on a local branch that was never pushed produces a tag pointing at a commit nobody else has. --verify-tag on gh release create catches this.
• Cherry-picks without -x make it impossible to audit which fixes reached which branch.
• Release branches that live past the next release accumulate fixes that never reach main. Merge back or compare with git cherry -v main release/2.4.
• Generated release notes list PR titles, not user impact. Curate them (changelog-writing).
• Pre-release tags must not be marked latest; package registries need a dist-tag such as npm publish --tag next so npm install does not pick up the RC.

Output

## Release v2.4.0 status
**Model:** release branch release/2.4, RC rc.3 (sha abc1234)
**Changes:** 31 PRs; risky: migration 0042, new tax engine (flagged)
**Go/no-go:** all criteria met except <item>
**Rollback plan:** linked; previous artefact sha256:...
**Pending confirmation:** push tag v2.4.0, publish GitHub release, start 5% rollout

Verification

• git rev-parse v2.4.0^{commit} equals the last RC commit, and the published artefact digest matches the RC’s.
• Release page shows the correct notes and is marked latest; RCs are marked pre-release.
• Rollback step 1 and 2 commands were dry-run or rehearsed in staging.