Releases and Branch Protection
The detail behind git-conventions.md § Release Process and § Branch Protection. The everyday
rules stay there: every change is a PR, required-check names are the contract, and a delivery PR
is never merged over a required check that is not green. Read this file before cutting a tag,
bumping a manifest version, cutting a release/* branch, or changing a ruleset or a required check.
Release Process
Releases are cut as annotated tags, never from a branch. A tag is immutable, so what the client tests is exactly what was handed over.
Tag format: v<major>.<minor>.<patch> — v0.1.0, v0.1.1, v1.0.0. Always annotated
(git tag -a v0.1.0 -m "Phase 1") so the tag carries its own message and date.
The tag format decides the environment, and pushing the tag deploys (F38-i decision 32):
| You do | It deploys to |
|---|---|
Merge to main |
dev |
Push vX.Y.Z-rc<N> |
UAT (the run stops at its first step while no UAT environment is applied) |
Push a plain vX.Y.Z |
production (from the day production is created; before then, nothing) |
| Create a branch | nothing (a manual dev deploy of a branch is still possible, AD #24) |
- Anyone with write access may push a release tag; there is no named-deployer list and no tag ruleset (F38-i decision 19). Push one only when the release is meant for the environment its format names, because pushing it deploys; Claude asks the lead before pushing one.
- An
-rc<N>tag never reaches production:deploy-prodstarts only on a plainvX.Y.Z(F38-i FR-6, FR-7). - The minor or major number bumps at a delivery-phase boundary (
v0.1.0Phase 1,v1.0.0V1 sign-off). - Every UAT candidate is an
-rc<N>tag, Phase 1’s round included, and each fix in the round is the next candidate of the same version, with no manifest bump. The rehearsal tookv0.1.0-rc1, so Phase 1’s round starts at the next free number (v0.1.0-rc2or higher). Every other rule in this section applies to an-rc<N>tag in the same way. - Acceptance is recorded against the accepted
-rctag, which is the release’s immutable handover record. - A plain
vX.Y.Zmeans “go live”: it is pushed on the accepted candidate’s commit when Empire wants that release live, and pushing it deploys to production (before production exists it deploys nothing). A hotfix to a live release is the only other plain tag (below). The plain tag is pushed inforge-et-be,forge-et-feandforge-et-pwa; the backend deploys and each frontend waits for the backend to report the tag’s version (F38-i FR-7). Then the person who pushed the tag runs the smoke suite against production, as after a dev deploy (.forge/team-guide.md§ After a dev deploy — the smoke run), and raises a failure as a bug (F38-i FR-12 item 2; the suite’s production target, behind an explicit production flag, is built by F38-i-WI-9.2). - Patch bumps only for a hotfix to a live release, cut from
release/vX.Y.Z. - An existing tag is redeployed by re-running its workflow run from the Actions page — for
example after a UAT instance is applied again — since a tag-push trigger does not fire again for a
tag that already exists. GitHub allows a re-run for 30 days; after that, push the next
-rc.
Tag only a commit whose checks passed, each in the one place it runs. The test suites and the
browser gates run on our own machines (the nightly full run on the lead’s Mac, and each PR’s records
and gate), and in CI only on a manual run that asks for them
(git-conventions.md § The test suites run locally, and the PR records them); CI runs the Fast lane (compile, static checks, the secret and
dependency scans) on a clean Linux runner.
- A tag on
main: pushes tomaindo not run CI, so before tagging rungh workflow run "PR validation" --ref main -f tests=falsein each app repo being released and tag the commit those runs passed on — the Fast lane only, since the nightly full run (below) ran the tests and the browser gates on that commit. A weekly scheduled run counts too when it ran on that commit. - A tag on
release/*: every push there runs the Fast lane, and each PR into it ran a full test record (every test, chosen for arelease/*base) and the full browser gate on its head, which theprotect-releasesruleset requires to be up to date with the branch before it merges, so the merge commit holds the files those runs tested.
A tag on main goes only on a commit the nightly full run passed in full (the lead, 2026-11-02,
with the browser gate taken off PRs into main — PRD Rev 81, test-run-cost.md S-4). CI’s pre-tag
run is the Fast lane only (-f tests=false, N-5) and runs no test suite and no browser, so a tag on
main also needs a night on which
every suite of each released repo passed (or was unchanged since passing) on the commit being
tagged: read the latest comment from a scheduled night on the harness issue labelled nightly-log
(not one whose heading says “started by hand”, which may have run only some suites), whose table
names each suite’s result and commit, and tag that commit, or wait for the next night. A suite still red, or a night that did not run,
means no tag. Why: with no full browser gate and only selected tests on a PR, the nightly run is the only
check of every browser spec at every size, and a tag deploys to UAT or production.
A backend release tag goes only on a commit dev built. UAT and production promote the image
the dev deploy built for the tagged commit, crm/backend:build-<full commit SHA>, and never
rebuild it (F38 FR-35, NFR-4), but some commits on main have none: a merge that changes only
workflow files does not deploy, and a waiting dev deploy is replaced by a newer one. Before
tagging forge-et-be, check that ECR holds the commit’s image (a read):
aws ecr describe-images --repository-name crm/backend --image-ids imageTag=build-<full SHA> --region us-east-1
When it has none, either run the dev deploy by hand on main’s head (gh workflow run build --repo altrium-io/forge-et-be --ref main), wait for it to finish, check ECR again and tag that
commit, or tag the nearest later commit that has an image. The hand-run dev deploy changes what
dev runs, so Claude asks the lead before dispatching it (.claude/CLAUDE.md § ASK FIRST). If
the check after the run still finds no image (a newer merge’s run took its place), tag the
nearest later commit that has one. The tagged commit must also meet the rule above: CI fully
tested it. deploy-uat stops on a commit with no image (F38-h FR-1); that is the backstop, not
the check.
A hotfix tag on release/vX.Y.Z also goes only on a commit with a dev-built image (F38-i
FR-15). A hotfix commit is not on main, so the fallback above does not reach it. When ECR has no
image for it, run the dev deploy by hand on the release branch (gh workflow run build --repo altrium-io/forge-et-be --ref release/vX.Y.Z; AD #24 allows a manual dev deploy of another branch),
wait for it to finish, check ECR again and tag that commit; if the check still finds no image (a
merge to main replaced the waiting run), dispatch it again. The run deploys the hotfix commit to dev
until the next merge to main deploys main again, so Claude asks the lead before dispatching it,
as for the main fallback.
Deployment targets:
| Environment | Deploys | Notes |
|---|---|---|
| Development | main, automatically on every merge (forge-et-be and forge-et-fe since Oct 2026, forge-et-pwa since 2026-10-25, to capture.dev.crm.empire.lk); a manual run may deploy another branch (AD #24, F38 Rev 18) |
Permanent. Build environment — never doubles as UAT |
| UAT | A tag | Temporary: one uat instance kept from Phase 1’s acceptance round to the end of Phase 2’s (terraform apply/destroy, AD #23) |
| Production | A tag | Permanent |
Phase handover sequence:
- Phase feature-complete on
main→ push the round’s first candidate (the next free-rc, in all three app repos; for Phase 1,v0.1.0-rc3if the earlyv0.1.0-rc2has gone out — F38-h spec Rev 15) → it deploys to the UAT environment. - UAT round runs. Defects are triaged into
bugs:and fixed onmain(fix/BUG-NNN-…), because nothing is live yet. A fix release is the next candidate: push the next-rcinforge-et-be,forge-et-feandforge-et-pwa; it redeploys UAT, each frontend waiting for the backend, and the CRM also for the capture app (F38-h FR-2, FR-13). - When the client accepts, record the acceptance against the accepted
-rctag, then movemain’s manifests to1.0.0in a PR in each app repo — or earlier, before the next phase’s first candidate, if the phase’s release is still open then (below). When the client elects to run the phase in production, push the plainv0.1.0on the accepted candidate’s commit inforge-et-be,forge-et-feandforge-et-pwa(it deploys once production exists) and cut the release branch from it, named after it (v0.1.0→release/v0.1.0). From this point, fixes for what is live go to the release branch ashotfix/*, are tagged with further patch bumps (v0.1.1,v0.1.2, …), and are merged back intomain. - Trunk work for the next phase continues on
mainthroughout — it is never blocked by a UAT round or by a live release. - Next phase feature-complete → tag
v1.0.0-rc<N>frommainfor its UAT round, thenv1.0.0at sign-off, each pushed in all three app repos. The Phase 1 release branch stops receiving fixes; it is kept, not deleted.
Manifest versions match the release. build.gradle (version) and each frontend’s
package.json (version) — all three app repos — carry the release version currently being
built toward, and at the commit a release tag points to, manifest and tag must agree (v0.1.0
tags a commit whose manifests read 0.1.0). The exception is Phase 1’s UAT round: main holds
0.1.0, the version every candidate of the round carries, not the 1.0.0 that Phase 2’s work
builds toward.
- Bumping is part of the release, not an afterthought.
main’s manifests stay on0.1.0until Phase 1’s UAT round is accepted, since a fix in the round is the next-rcof the same version, and after acceptance a PR in each app repo movesmainto1.0.0. Movingmainto1.0.0as soon asv0.1.0-rc1is tagged would make every later candidate in the round fail the version check. IfP1is still open when Phase 2’s first candidate is due, the bump comes first, whichever happens first:P1may stay open while Phase 2 is built (.claude/rules/tracker.md § Release & UAT Lifecycle), andv1.0.0-rc<N>would faildeploy-uat’s version check on0.1.0.P1’s remaining fixes are then re-tested on Phase 2’s candidates (UC-1round 2 on av1.0.0-rcbuild), so Phase 1 is accepted on that candidate and has no separatev0.1.0production release; whether to take Phase 1 live from av0.1.0candidate before then is the lead’s call. A hotfix PR onrelease/vX.Y.Zbumps the patch in the same PR as the fix, so the tag that follows the merge matches. - An
-rc<N>suffix lives in the tag only, and every version check ignores it. Manifests read1.0.0whilev1.0.0-rc1is under UAT, and0.1.0for the rehearsal’sv0.1.0-rc1.deploy-uatin each app repo and the smoke suite’suattarget compare the manifest with the tag stripped of its leadingvand any-rc<N>suffix (F38-h FR-1, FR-2, FR-11). - The release’s app repos are bumped and tagged together —
forge-et-be,forge-et-feandforge-et-pwa, for every release — at the same version, even when only one of them changed, becauseforge-et-fe’sdeploy-uatchecks that the backend’s/actuator/infoand the capture app’s page report the version of its own tag (F38-h FR-2, FR-13). The runs in all three repos start together on the tag push; each frontend’s waits for the backend to report the tag’s version before it deploys (F38-i decision 22), and the CRM’s also waits for the capture app.forge-et-pwajoined from Phase 1’s round’s first-rcafter the rehearsal, the release that first deploys it to UAT (F38-h spec Rev 12), so the three manifests match from then on, and a Phase 1 release run in production deploys all three (F38-i FR-15, Rev 4). - The running system reports its version. Backend:
springBoot { buildInfo() }inbuild.gradle, so/actuator/infoanswers “which version is this environment running?” as an HTTP call. Frontends: the bundle exposespackage.json’s version (Vite injects it at build time) so a deployed bundle is identifiable from the browser. - Every running artifact is traceable to version and commit. The dev deploy tags each backend
image
build-<full commit SHA>, and no workflow builds an image from a tag:deploy-uatadds the release tag to the image dev built for the tagged commit, which keeps itsbuild-<full commit SHA>tag (F38-h FR-1). A frontend bundle is built from the tag for each environment (F38-h NFR-4).
Each phase’s UAT round has its own release in tracker.yaml’s releases: list (P1, P2; see
.claude/rules/tracker.md → “Release & UAT Lifecycle”). A release records its sign-off and, in its
live marker, its first production deploy; every deploy, that one included, is also recorded by
its tag, and a later one (a hotfix patch) only by its tag. P2’s sign-off is V1 sign-off.
Branch protection rulesets
Applied to main in all four delivery repos, and to release/* in the three app repos;
the read-only forge-et-pwa-poc reference repo needs none of this — the team never
pushes to it. The mechanism is GitHub rulesets (protect-main in every delivery repo,
protect-releases in the app repos), not classic branch protection: creation and deletion
are explicit named rules rather than inferred behaviour, anyone with read access can
inspect them, and bypass is an explicit actor list. The rules besides the required status
checks (git-conventions.md § Branch Protection), which each ruleset also carries:
| Rule | main |
release/* |
|---|---|---|
| Require a pull request before merging | ✅ | ✅ |
| Required approvals | 0 | 1 |
| Require review from Code Owners | — | ✅ |
| Block force pushes | ✅ | ✅ |
| Block deletions | ✅ | ✅ |
| Require the branch to be up to date before merging | — | ✅ (app repos) |
The up-to-date rule on release/* is what lets the PR’s local records stand for the merge commit: a
push there runs the Fast lane only, never the suites (§ Release Process).
On main the PR rule’s “approval for unattributed changes” option is also off; with no
approval required it would only re-add one when someone else pushed a commit to the branch.
Restoring the approval on main means setting the count back to 1 and re-enabling Code Owner
review in each repo’s protect-main ruleset (repo admin).
Consequences that follow from these rules:
- No direct pushes on either branch — every change is a PR, except the DevOps team’s deploy
files, which an organisation administrator pushes with the bypass and the team checks after the
fact (
git-conventions.md§ Branch Protection). Onmainthe author may merge their own PR once the required checks pass; onrelease/*a Code Owner other than the author must approve (Code Owner review resolves through.github/CODEOWNERS). - History on shared branches is immutable. Correcting a pushed commit message means a new commit, not an amend — force-push is blocked. Rewriting a branch that an open PR points at also invalidates that PR, which GitHub closes and will not reopen.
- Release branches persist. Deletion is blocked deliberately; they are the shipped record.
- Release branches can still be cut on write access. Rulesets restrict creation only via an
explicit “restrict creations” rule, which is deliberately not enabled. Probe-verified with the
ruleset active and no bypass: creating
release/*succeeds, a direct push is rejected (“Changes must be made through a pull request”), deletion is rejected. Tags are unrestricted, so cutting a release tag needs no elevated access either. - Creating a
release/*branch does not need the required checks.protect-releasessetsdo_not_enforce_on_create: true: the commit a release tag points at is a merge onmain, which has noForge reviewstatus of its own. Every later change still goes through a PR under all the checks. Not yet probe-verified by a member without admin (designforge-review-gate.md, AC-10); an admin’s bypass would create the branch whatever the setting.
All three app repos require two workflow jobs, Fast lane and Slow lane, and two commit
statuses: Test record, the local record of the test suite
(.claude/rules/git-conventions.md § The test suites run locally, and the PR records them), and
Forge review, the review record (.claude/rules/review-record.md). A person’s login sets each
status; a workflow sets both on a documentation-only PR and Forge review on a Dependabot PR, so
both are required from “any source”.
Administrator bypass is left available so a genuine emergency is not blocked, and the DevOps
team’s deploy-file pushes use it too (git-conventions.md § Branch Protection) — on rulesets
that is the explicit bypass list, the Repository admin role: whoever holds admin on the repo.
Check who that is with gh api repos/altrium-io/<repo>/collaborators --jq '.[] | select(.permissions.admin) | .login'.