feat(release): add Cut Pre-release Tag workflow (#2677) - #3253

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request centralizes the creation of pre-release tags into a dedicated GitHub Actions workflow. By moving this responsibility to a CI-driven process, the repository can now enforce strict tag-creation rules, ensuring that all pre-release and stable tags are generated exclusively by the CI app. This change improves security and consistency in the release process while providing a clear path for enabling repository-wide tag protection.

Highlights

• New Pre-release Workflow: Introduced cut-prerelease.yaml as the centralized, CI-driven entry point for creating pre-release tags (alpha, beta, rc), replacing manual git pushes.
• Hardened Tag Enforcement: Enables the transition from manual tag-creation discipline to hard enforcement via GitHub tag rulesets, allowing only the CI app to create pre-release and stable tags.
• Documentation Updates: Updated docs/release.md to reflect the new workflow, clarify release types, and provide guidance on the required rollout order for tag-protection rulesets.

No actionable comments were generated in the recent review. 🎉

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

Verdict

LGTM with non-blocking notes

Clean, defensively-written CI/docs PR. It adds cut-prerelease.yaml (a workflow_dispatch that becomes the single entry point for creating pre-release tags, pushed under the CI App identity), migrates the docs off the manual git push origin HEAD:refs/tags/<tag> recipe, and completes SHA-pinning on the touched workflows. No CRITICAL or MAJOR issues. This review is the consolidation of two independent passes (Opus + Fable); findings 1–3 are worth addressing but none blocks merge.

What was verified (checked, not assumed)

• Supply-chain pins are authentic. Every newly-pinned SHA resolves to a real upstream release and the # vN comment is accurate: actions/checkout@34e11487… → v4 / v4.3.1; actions/create-github-app-token@d72941d7… → v1 / v1.12.0; actions/github-script@f28e40c7… → v7 / v7.1.0. All match the pins already in tags.yaml, so the PR makes the touched workflows internally consistent. Repo-wide there are now zero @vN refs for checkout / create-github-app-token.
• GITHUB_TOKEN recursion claim is correct. Pushes made with the default GITHUB_TOKEN do not trigger push-event workflows; an App-token push does. Checkout passes the app token and persists it as origin's credential (persist-credentials defaults on), so the later bare git push origin "HEAD:refs/tags/$TAG" is app-authenticated and tags.yaml fires. Already the mechanism used by promote-rc.yaml / retention.yaml.
• Write-once is enforced by git itself. The pre-checks are TOCTOU-racy in principle, but the final push is non-forced and git rejects a non-forced push to an existing tag ref; the global concurrency: cut-prerelease (cancel-in-progress: false) additionally serializes dispatches. Three layers.
• Least privilege is real. Workflow-level permissions: contents: read is correct (the push uses the app token, not GITHUB_TOKEN), and the app token is scoped repositories: ${{ github.event.repository.name }} — tighter than the installation-wide token tags.yaml mints.
• No injection. inputs.tag reaches shell/JS only via env: + process.env; the regex is anchored; branch names can't contain newlines, so the ::error:: interpolations are safe.
• Docs ruleset claims hold against the code. Checked nightly.yaml, retention.yaml, promote-rc.yaml, pull-requests-release.yaml: nothing moves or deletes a v* git tag (retention prunes GHCR OCI tags only; promote-rc force-pushes only staging branches), and finalize pushes the stable + api/apps/v1alpha1 tags via the app-token remote — so the proposed "Restrict creations, CI app sole bypass" ruleset would not break the promote flow. No leftover "push by hand" recipe remains, and the workflow count / cross-references in docs/release.md are consistent ("five workflows", all referenced files exist).

Findings

1. [MINOR] main dispatch accepts any version line

cut-prerelease.yaml:113-126 — the line-consistency check constrains only release-* dispatches. From main, any tag is accepted, and downstream tags.yaml Get base branch also accepts main for any tag. So v1.2.5-rc.1 (a patch-line rc) or an old-line v1.4.0-rc.9 can be cut from main, producing a patch-rc built from main content and a wrong-tree staging branch. This contradicts the file's own header comment ("main for a new minor's pre-release (vX.Y.0-rc.N)") and the PR body's "matching release-X.Y branch". Cheap fix: for a main dispatch, require the patch digit Z == 0 (parse already captures it).

2. [MINOR] Stale-tip race can burn a write-once tag name, with a misdiagnosing error

cut-prerelease.yaml:91-98,148-153 + tags.yaml:119 — for workflow_dispatch, checkout (no explicit ref:) pins HEAD to the dispatch-time SHA, not the branch tip at push time. If the branch advances between dispatch and the push step (the window includes any wait in the cut-prerelease concurrency queue), the tag is pushed at a non-tip commit, base_ref comes up empty, and tags.yaml fails — fail-closed, but (a) the write-once tag name is already consumed (maintainer must bump N), and (b) tags.yaml:119's new message ("Cut pre-release tags with the 'Cut Pre-release Tag' workflow … which pushes the tag correctly") misdiagnoses this case, since the workflow was used. Mitigation: right before the push, compare git rev-parse HEAD against git ls-remote origin "refs/heads/$GITHUB_REF_NAME" and fail with "branch advanced since dispatch, re-run" if they differ.

3. [MINOR] PR-body rationale is factually wrong (the change is still justified)

The "Why" section claims "fnmatch has no way to match v* except v*-rc.*", i.e. that a ruleset cannot restrict stable-tag creation while allowing hand-pushed pre-releases. GitHub repository rulesets support separate include and exclude ref-name patterns (verified against GitHub docs), so a "Restrict creations" ruleset with include: refs/tags/v* + exclude: refs/tags/v*-* expresses exactly "stable tags only" today, without this workflow. The workflow's real, independent benefits (audit trail, single entry point, guaranteed base_ref, app-identity push so tags.yaml fires, and enabling creation control over all of v*) stand on their own — but the stated impossibility isn't the actual reason. Worth correcting in the description so future readers don't inherit a false constraint. (Code and committed docs are unaffected — this is PR-description-only.)

4. [NIT] git ls-remote failure is indistinguishable from "tag absent"

cut-prerelease.yaml:138 — git ls-remote --exit-code … >/dev/null 2>&1 treats a transport/auth failure (exit 128) the same as "tag not found" (exit 2). Harmless (the non-forced push is the real enforcement), but checking specifically for exit 2 would avoid a misleading pass.

5. [NIT] Full-history clone for a single ref push

cut-prerelease.yaml:94-95 — fetch-depth: 0 + fetch-tags: true clones the whole monorepo history just to push one ref. fetch-depth: 1 suffices; the local tag pre-check at line 134 is redundant with the live ls-remote on line 138 anyway.

6. [NIT] Validation runs after token mint + checkout

Branch/ref-type validation and the existing-tag check run only after the app token is minted and a full checkout completes; a wrong-branch or already-taken-tag dispatch still mints a token and clones before failing. Reordering the pure-input validation first would fail faster. Cosmetic (the token auto-revokes in the action's post step).

Phase 5b (existing-customer upgrade + fresh install)

N/A. The diff touches only .github/workflows/* and docs/release.md — no packages/, charts, ApplicationDefinition, RBAC, or migrations, so there is no tenant upgrade or fresh-install surface. The only operational dependency is the documented rollout ordering (enable the Restrict creations ruleset only after this workflow ships), which the PR calls out explicitly and correctly.

Summary

Well-scoped and correctly reasoned; the core mechanism follows the repo's pre-existing, documented convention, and the PR honestly flags that the live runtime path is unproven until first real dispatch. Recommend merging after (optionally) tightening the main-dispatch version check and correcting the PR-body rationale.

Thanks IvanHunters — thorough review, and the finding-3 catch is a good one. Addressed all six plus a write-access gate (pushed as fix(ci): address review findings):

1. [MINOR] main accepts any version line — fixed. parse now also emits the patch digit; a main dispatch is rejected unless Z == 0 (a new minor's vX.Y.0-*). Patch-line pre-releases must come from their release-X.Y branch.
2. [MINOR] Stale-tip race — fixed. Right before the push, the step compares local HEAD against git ls-remote origin refs/heads/<branch> and fails with "branch advanced since dispatch, re-run" if they differ — so it no longer tags a stale commit or burns the write-once name on an empty-base_ref failure.
3. [MINOR] PR-body rationale wrong — you're right, rulesets express stable-only creation via include + exclude patterns. Corrected the PR description; the impossibility claim is gone and the "Why" now states the workflow's actual value (locking pre-release creation to CI, which the exclude-pattern approach can't). Committed docs were unaffected, as you noted.
4. [NIT] ls-remote conflates exit 128 and 2 — fixed. It now treats only exit 2 as "absent"; any other non-zero fails as a transport/query error.
5. [NIT] Full-history clone — fixed. fetch-depth: 1, dropped fetch-tags, and removed the redundant local tag pre-check (the live ls-remote is the real enforcement).
6. [NIT] Validation after token mint + checkout — fixed. Tag parse + dispatch-branch validation now run first; the token is minted and checkout happens only after.

Separately added a write-access gate: a getCollaboratorPermissionLevel check requires the dispatcher to have admin/maintain/write and fails closed otherwise. workflow_dispatch already requires write to trigger, so this is auditable defense-in-depth.

The runtime path (app-token push, base_ref, and now the permission gate) is still only provable on the first real dispatch — flagged in the PR body.

IvanHunters thanks again for the re-review. Addressed the two remaining nits:

• 'maintain' inert entry — dropped; allowed is now ['admin', 'write'] (the legacy permission field never returns maintain, as you noted).
• stale-tip guard exit-code masking — the remote-tip resolution no longer pipes through cut with the exit code masked; a transport failure now reports distinctly, consistent with the write-once check above it.

The push dismissed your approval — mind re-approving when you get a chance? Only those two nits changed since your LGTM. CI is re-running.