source: .claude/rules/release-and-branch-protection.md · generated — edit the markdown, not this file

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-prod starts only on a plain vX.Y.Z (F38-i FR-6, FR-7).
  • The minor or major number bumps at a delivery-phase boundary (v0.1.0 Phase 1, v1.0.0 V1 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 took v0.1.0-rc1, so Phase 1’s round starts at the next free number (v0.1.0-rc2 or higher). Every other rule in this section applies to an -rc<N> tag in the same way.
  • Acceptance is recorded against the accepted -rc tag, which is the release’s immutable handover record.
  • A plain vX.Y.Z means “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 in forge-et-be, forge-et-fe and forge-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 to main do not run CI, so before tagging run gh workflow run "PR validation" --ref main -f tests=false in 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 a release/* base) and the full browser gate on its head, which the protect-releases ruleset 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:

  1. 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-rc3 if the early v0.1.0-rc2 has gone out — F38-h spec Rev 15) → it deploys to the UAT environment.
  2. UAT round runs. Defects are triaged into bugs: and fixed on main (fix/BUG-NNN-…), because nothing is live yet. A fix release is the next candidate: push the next -rc in forge-et-be, forge-et-fe and forge-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).
  3. When the client accepts, record the acceptance against the accepted -rc tag, then move main’s manifests to 1.0.0 in 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 plain v0.1.0 on the accepted candidate’s commit in forge-et-be, forge-et-fe and forge-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 as hotfix/*, are tagged with further patch bumps (v0.1.1, v0.1.2, …), and are merged back into main.
  4. Trunk work for the next phase continues on main throughout — it is never blocked by a UAT round or by a live release.
  5. Next phase feature-complete → tag v1.0.0-rc<N> from main for its UAT round, then v1.0.0 at 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 on 0.1.0 until Phase 1’s UAT round is accepted, since a fix in the round is the next -rc of the same version, and after acceptance a PR in each app repo moves main to 1.0.0. Moving main to 1.0.0 as soon as v0.1.0-rc1 is tagged would make every later candidate in the round fail the version check. If P1 is still open when Phase 2’s first candidate is due, the bump comes first, whichever happens first: P1 may stay open while Phase 2 is built (.claude/rules/tracker.md § Release & UAT Lifecycle), and v1.0.0-rc<N> would fail deploy-uat’s version check on 0.1.0. P1’s remaining fixes are then re-tested on Phase 2’s candidates (UC-1 round 2 on a v1.0.0-rc build), so Phase 1 is accepted on that candidate and has no separate v0.1.0 production release; whether to take Phase 1 live from a v0.1.0 candidate before then is the lead’s call. A hotfix PR on release/vX.Y.Z bumps 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 read 1.0.0 while v1.0.0-rc1 is under UAT, and 0.1.0 for the rehearsal’s v0.1.0-rc1. deploy-uat in each app repo and the smoke suite’s uat target compare the manifest with the tag stripped of its leading v and 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-fe and forge-et-pwa, for every release — at the same version, even when only one of them changed, because forge-et-fe’s deploy-uat checks that the backend’s /actuator/info and 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-pwa joined from Phase 1’s round’s first -rc after 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() } in build.gradle, so /actuator/info answers “which version is this environment running?” as an HTTP call. Frontends: the bundle exposes package.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-uat adds the release tag to the image dev built for the tagged commit, which keeps its build-<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). On main the author may merge their own PR once the required checks pass; on release/* 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-releases sets do_not_enforce_on_create: true: the commit a release tag points at is a merge on main, which has no Forge review status of its own. Every later change still goes through a PR under all the checks. Not yet probe-verified by a member without admin (design forge-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'.

Generated from .claude/rules/release-and-branch-protection.md by .claude/lib/render-docs-html.js. Markdown is canonical.