feat(release): cutting an rc freezes the line into release-X.Y - #3399

Code Review

This pull request introduces a mechanism to enforce that in-tree image pins on the main branch are set to a sentinel tag (v0.0.0-dev) to prevent stale pins from quietly running old code. It adds a pre-commit hook and a validation script hack/check-image-pins.sh to check and reset these pins, updates the release documentation to reflect this workflow, and resets various package image tags to the sentinel. The review feedback suggests improving the robustness of hack/check-image-pins.sh by explicitly verifying that rg (ripgrep) is installed to avoid silent failures, and dynamically extracting the parent path of split-shape pins using ${dig_path%.*} instead of assuming a .digest suffix.

Actionable comments posted: 2

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/release.md`:
- Line 39: Repair the Backporting link in the release documentation by changing
its fragment to match the actual rendered slug of the Backporting heading, or
rename that heading to produce `#backporting`. Ensure the link resolves correctly
and clears markdownlint MD051.
- Around line 146-150: The patch-release Mermaid diagram in docs/release.md
still depicts release-1.2 being created after v1.2.0. Update the diagram to show
the release-1.2 branch already existing from the RC freeze, consistent with the
surrounding cherry-pick procedure and release-X.Y freeze model.

LGTM — the rc-freeze mechanism, the backport-target rewrite, and the docs are correct and internally consistent; the one robustness gap in the freeze failure path is a strict improvement over today's behavior, not a regression, so it is a recommendation rather than a blocker.

Business context: cutting the first vX.Y.0-rc.N now creates release-X.Y at the tagged commit and freezes the line, so features merged to main after the rc no longer leak into the release, and later cuts plus fixes come off the branch.

I traced every doc claim against the actual workflow code and every failure path through the new shell, and the core design holds up: the freeze is create-only and idempotent (a later rc.N no-ops on the existing branch, the push is non-forced), it is correctly gated to kind == 'rc' && patch == '0', the refuse-from-main step blocks a frozen line while still allowing a genuinely new minor, and creating release-X.Y triggers no extra workflow (nothing keys on push to release-* or on create). The GitHub Actions default shell is bash -eo pipefail, so the freeze step's ls-remote | cut fails closed on a transport error rather than silently reading "absent".

Non-blocking follow-ups

1. The tag push and the freeze push are not atomic, and the failure path has no clean re-run (worth hardening). The rc tag is pushed in one step, then release-X.Y is created in a later step — two independent git push calls. If the tag push succeeds and the freeze push then fails (transient blip, runner eviction), the tag exists but the line is not frozen, and a same-tag re-dispatch is refused by the write-once tag guard, so recovery is manual. I am flagging this as non-blocking rather than blocking because it never pushes a wrong ref or corrupts anything, it fails loudly, it degrades to exactly the behavior main has today (the maintenance branch is still created later by the finalize step's create-if-missing), and it is recoverable with a one-line push — so the change is a strict improvement that is never worse than the status quo. Cheapest hardening: for the first-rc case push both refs together (git push --atomic origin "HEAD:refs/tags/$TAG" "HEAD:refs/heads/release-$LINE") — after validating it does not disturb the populated base_ref the tag push relies on — or, at minimum, print the manual recovery command in the step's failure message so an operator is not left guessing.

2. ls-remote exit-code handling is inconsistent in the freeze step. The refuse step, the write-once guard, and the stale-tip guard all carefully distinguish "absent" (exit 2) from a transport/auth failure; the freeze step's git ls-remote --heads origin "refs/heads/$BRANCH" | cut -f1 does not. It is safe in practice (pipefail fails the step on a real error, and the follow-up non-forced push fails closed on any conflict), but aligning it with the pattern used three times above it removes a stumbling block for the next reader.

3. Broken intra-doc anchor. docs/release.md line 39 links to #backporting, but the heading is ## Backports, whose slug is #backports; the link resolves nowhere. One-character fix.

4. Backport label/reference descriptions lag the new behavior. The rewrite drops the contiguous-minor assumption (previous is now the second-newest existing line, not Y-1), but docs/release.md's backport-bot table still shows backport-previous -> release-X.(Y-1), and .github/labels.yml still describes the labels in the old terms. Tightening both to "newest / second-newest existing release line" keeps the reference matching the code.

5. Patch-release diagram contradicts its own prose. The prose says release-X.Y already exists from the freeze ("there is no branch to create"), but the adjacent mermaid graphs still branch release-1.2 at the v1.2.0 commit. It reads as a simplification, but it visually contradicts the sentence right above it.

6. The release label makes the release-asset check fail on this branch. A triage bot applied the bare release label, which activates the release-asset resolution job; that job expects a release-X.Y.Z-named branch and fails on this feature branch. This is a labeling artifact, not a defect in the diff — removing the release label clears the red check.

What I verified and found correct

• The promote PR base flips to release-X.Y on its own: promote-rc.yaml already selects release-${LINE} when it exists, else main — the doc claim is accurate and needs no code change.
• Finalize's "Ensure maintenance branch" becomes a no-op: it updates fast-forward-only (force:false, warns on non-fast-forward) and creates-if-missing, and with the promote PR merging into release-X.Y the merge commit is already the branch tip.
• Backport rewrite: numeric descending sort fixes both the release-1.10 > 1.9 ordering and the min-1 non-existent-branch bug; the ^release-(\d+)\.(\d+)$ anchor correctly excludes release-X.Y.Z staging branches; pagination handles the large branch list.
• The app token already creates release-* branches in the finalize step, so the freeze push is authorized by the same identity.

NOT LGTM. One thing left, same class as last round: the tree now disagrees with itself about which releases route their changelog through the backstop.

Business context: cutting the first vX.Y.0-rc.N now creates release-X.Y at the tagged commit and freezes the line, so later rcs and the promoted stable ship only rc-validated content instead of silently absorbing whatever merged to main since rc.1.

Stale comments

This PR rewrites docs/release.md to say the promote PR targets release-X.Y for every release now, and that the tags.yaml backstop is the only route a published changelog takes to main. promote-rc.yaml:846 prefers the line whenever it exists, and after the freeze it always does. Three comments still describe the old model where that was a patch-release corner case:

• .github/workflows/tags.yaml:343-357, the generate-changelog header: "self-skips on the normal path ... finds the changelog already on origin/main", with "a patch release whose promote PR targeted release-X.Y" as case 2. After the freeze the port-to-main case is the normal path and the self-skip is the exception, so the framing is inverted.
• .github/workflows/pull-requests-release.yaml:335-343: "a patch release whose promote PR targets release-X.Y would never be synced at all". The mechanism is right, the qualifier is wrong: that is every release now. You fixed this exact sentence in the doc's Phase 6 section.
• hack/release-changelog-contract.bats:240, the comment above the ports-not-regenerates test: same "(a patch release)" qualifier.

These comments are the first thing whoever debugs a missing changelog reads, and they now point at the wrong model of which path is normal. Reword them to the freeze model; prose only, no test needed.

Non-blocking

build-release.yaml's new workflow_dispatch takes any ref, and the "Run workflow" UI preselects main, which is exactly where the recovery messages send the operator. A mis-click burns a 2-hour make build publishing cozystack-packages:main in a race with build-main.yaml, the same tag-collision class as #2711. Content is never mislabeled since IMAGE_TAG is github.ref_name, so a mis-dispatch wastes a runner and nothing else. A guard step refusing refs that do not match ^release-[0-9]+\.[0-9]+$ closes it in five lines.

release-* still has no protection ruleset (from last round; repo setting, not code). The freeze makes an unprotected branch the release's only content path for the whole stabilisation window, so this got more urgent.

Actionable comments posted: 3

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/build-release.yaml:
- Around line 38-50: Add an initial guard to the manually dispatched release
workflow, before checkout and credential setup, requiring github.ref_type to be
branch and github.ref_name to match the release-X.Y pattern; reject all other
refs before publishing. Apply this invariant to each affected workflow section
and add matching assertions to hack/release-freeze-contract.bats.

In `@hack/release-freeze-contract.bats`:
- Around line 85-99: Update the force-detection assertions in both freeze step
blocks, including the block covered by the second referenced range, to reject
push refspecs beginning with “+” such as “+HEAD:refs/heads/$BRANCH”. Extend the
checks around the existing git push validation without changing the required
non-forced create-push assertion.
- Around line 74-82: Update the assertions in the affected tests around the
freeze, subsequent release, and related step blocks to run each condition grep
against its already extracted step_block rather than the complete workflow.
Within the freeze step block, also assert that id: freeze is present, ensuring
the guarded assertions cannot be satisfied by unrelated steps.

LGTM. All three comment sites now read correctly against the freeze model, and the two extra spots in tags.yaml were the same class, good catch. The build-release guard is stricter than what I asked for: ref_type plus the both-ends-anchored pattern also keep a release-named tag and the staging branches out, and the ordering pin puts it before checkout and the OCIR login. I mutation-tested the rescoped bats file: unanchoring the guard pattern, neutralizing the REF_TYPE comparison, and a flagless +HEAD: force refspec each turn the suite red.

One nit, not blocking: docs/release.md line 46 says promotion "fast-forwards the release-X.Y maintenance branch the freeze already created", but the promote PR merges into release-X.Y, so the merge commit already is the branch tip and finalize's ensure step is a no-op. Lines 102 and 297 of the same doc say exactly that; the line 46 wording reads like the branch moves at promotion.

The release-* protection ruleset from the previous round stays open as a repo setting.

LGTM with non-blocking notes. The logic is correct, behavior matches the description, and the cross-file claims check out. No regressions; this is safe to merge. A few robustness notes below, none blocking.

Verified

• kind parsing: m[4] of ^v(\d+)\.(\d+)\.(\d+)-(alpha|beta|rc)\.(\d+)$ is indeed the pre-release kind; the freeze gate kind == 'rc' && patch == '0' is right.
• Guard ordering (refuse-from-main before the tag push, freeze after it) is correct; freeze is create-only and no-ops on a later rc.N, and the branch forks exactly from the tagged commit.
• The "promote PR base flips to release-X.Y" claim holds: promote-rc.yaml already sets BASE="release-${LINE}" when the branch exists, and finalize does not filter on the PR base, so a promote PR into release-X.Y still finalizes and Ensure maintenance branch degrades to a fast-forward no-op. The docs narrative is accurate.
• Backport sorting: numeric descending correctly orders release-1.10 > release-1.9, and ^release-(\d+)\.(\d+)$ does not match the release-X.Y.Z / release-X.Y.Z-rc.N staging branches.

Non-blocking notes

1. Freeze guarantee has a residual hole in the documented branch-push-failure window (cut-prerelease.yaml, "Refuse to cut a frozen line from main"). The guard tests "does release-X.Y exist", but the invariant it protects is "no rc for this line was ever cut from main". These diverge exactly when the tag push of rc.1 succeeds and the freeze push fails: tag exists, branch does not. If the operator then dispatches rc.2 from main instead of running the recovery command, the guard passes, the tag lands on main's advanced tip (absorbing everything merged since rc.1), and the freeze step creates release-X.Y at that later tip. This is the exact silent feature leak the mechanism exists to prevent, and the step comment "Nothing is silently wrong in the meantime" does not hold for that path. Not a regression (there was no freeze before), but a cheap hardening is to also check for an already-cut tag of the line in the refuse step (e.g. git ls-remote --tags origin "refs/tags/v$LINE.0-rc.*"), so the guard fires on "tag exists, branch missing" too.

2. A backport-previous request that cannot be satisfied also kills the valid current leg (backport.yaml, "Determine target branches"). core.setFailed fails the whole prepare job, so the backport job (needs: prepare) never starts, including the correct current-line backport. With only one release line present, a PR carrying both backport and backport-previous opens neither backport, so the current-line fix is silently missed. Same all-or-nothing shape as the previous getBranch probe, so not a regression, but this PR rewrites the block and the comment above it says enumeration made failures impossible. Consider not failing the current leg when only the previous line is unsatisfiable, or soften the comment.

3. Leading zeros are accepted in the tag parse (cut-prerelease.yaml, parse step, pre-existing). (\d+) accepts v1.06.0-rc.1; the typo would create a stray release-1.06, and in backport.yaml both release-1.6 and release-1.06 parse to {maj:1,min:6}, a sort tie resolved by API listing order, which can reroute backports. Low probability, cheap to reject in the regex.

4. Minor TOCTOU in the freeze-create step (cut-prerelease.yaml, "Freeze the line"). When the branch already exists the step prints "leaving it untouched" and exits 0 without checking EXISTING == HEAD. If the branch were concurrently created at a different commit, tag and branch would diverge while the run reports success. No concurrent creator exists in normal operation, so this is largely theoretical; an EXISTING == HEAD assertion would close it.

5. The backport label's meaning shifts during a freeze window (by design). From rc.1 until vX.Y.0 ships, backport targets the frozen, not-yet-released line, and reaching the currently published stable requires backport-previous. In-flight PRs labeled backport under the old "latest published stable" semantics will land on the frozen line. Documented and intentional; noting it for any PRs already labeled when this merges.