Skip to content

Commit 6b1e170

Browse files
myasnikovdaniilmyasnikovdaniil
authored
feat(release): add Cut Pre-release Tag workflow (#2677) (#3253)
## What this PR does Adds `cut-prerelease.yaml` — a `workflow_dispatch` that becomes the **sole entry point for creating a pre-release tag** (`vX.Y.Z-alpha.N` / `-beta.N` / `-rc.N`), replacing the manual `git push origin HEAD:refs/tags/<tag>`. ## Why #2677 makes stable tags immutable, but tag *creation* was still only convention-enforced for **pre-releases**. Repo rulesets **can** already restrict *stable* `vX.Y.Z` creation to CI — a "Restrict creations" ruleset targeting `v*` with an exclude pattern for `v*-*` covers stable tags without any new workflow. What that approach **cannot** cover is pre-releases: `-rc` / `-alpha` / `-beta` tags were hand-pushed, so they can't be locked to CI while they still have a human entry point. This workflow closes that gap by making CI the sole creator of pre-release tags too. With it in place, an admin can extend "Restrict creations" (CI app as sole bypass) to **all** of `v*` — pre-release and stable alike — instead of only the stable subset. _(Correction: an earlier version of this description claimed a ruleset couldn't express "stable-only" creation. It can, via include + exclude patterns — thanks @IvanHunters. The workflow's real value is extending creation-control to pre-release tags, plus the audit trail, single entry point, guaranteed `base_ref`, and app-identity push that makes `tags.yaml` fire.)_ ## How it works - Generates the CozyStack CI app token (same app as `promote-rc.yaml`) and pushes the tag **as the app** — so `tags.yaml` fires (a tag pushed with the default `GITHUB_TOKEN` would not) and the push event's `base_ref` is populated (`tags.yaml`'s *Get base branch* step requires it). - Validates `^v\d+\.\d+\.\d+-(alpha|beta|rc)\.\d+$` and **rejects stable `vX.Y.Z`** — stable tags are cut write-once by the promote flow at a PR merge commit, never here. - Gates on the dispatcher having **write access** to the repo (`workflow_dispatch` already requires it; the explicit check is auditable defense-in-depth that fails closed). - Enforces dispatch from `main` (new minor's `vX.Y.0-*` only) or the matching `release-X.Y` branch; write-once (refuses an existing tag) with a stale-tip guard so a branch that advanced since dispatch fails cleanly instead of burning the tag name. - Pushes `HEAD:refs/tags/<tag>` from the branch tip — the exact form `docs/release.md` prescribes. Runs on `ubuntu-latest` (no build runner needed). Also updates `tags.yaml`'s two human-facing error messages and `docs/release.md` (the RC and patch flows, the workflow list, and a new repo-side tag-ruleset enforcement note) to point at the workflow instead of a manual push. Completes SHA-pinning on the touched release workflows (`nightly.yaml`, `promote-rc.yaml`, `retention.yaml`) — the zizmor "Audit workflows" gate was red on `main` for those. ## Rollout ordering The two `v*` tag rulesets have a hard order (now documented in `docs/release.md`): 1. **Immutability** (*Restrict updates* + *deletions*, no bypass) — safe to enable at any time; nothing in the flow ever moves or deletes a `v*` tag. 2. **Creation control** (*Restrict creations*, CI app sole bypass) — enable **only after this PR ships**, since this workflow is what makes CI the sole creator of pre-release tags. Enabling it earlier would lock maintainers out of cutting rc/alpha/beta. ## Validation - `actionlint` — clean. - `act -l` — job graph resolves (`cut` / `workflow_dispatch`). - `zizmor --offline` — no findings across the whole workflows dir (SHA-pinned actions, least-privilege `contents: read`). - Run blocks `bash -n` syntax-checked. - **Untested locally:** the workflow runtime (app-token auth, the real tag push, `base_ref` population, the `getCollaboratorPermissionLevel` gate) needs a live run with the CI secrets — the same "orchestration is unproven until it runs" caveat #3017 carried. ## Review follow-up Addressed the non-blocking findings from @IvanHunters' review (commit `fix(ci): address review findings`): 1. **[MINOR]** `main` dispatch now requires patch `Z == 0` (a new minor's pre-release), so a patch-line rc can't be cut from `main` content. 2. **[MINOR]** Added a stale-tip guard: if the dispatch branch advanced between dispatch and push, fail with a re-run hint instead of tagging a stale commit / burning the write-once name on an empty-`base_ref` failure. 3. **[MINOR]** Corrected the PR-body rationale above (rulesets can express stable-only creation via include + exclude). 4. **[NIT]** `ls-remote` now distinguishes "tag absent" (exit 2) from a transport/auth failure. 5. **[NIT]** Shallow checkout (`fetch-depth: 1`, no `fetch-tags`); dropped the redundant local tag pre-check. 6. **[NIT]** Pure-input validation now runs before the token mint + checkout (fail-fast). Plus a **write-access gate** on the dispatcher, requested separately. Part of #2677. ## Release note ```release-note NONE ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a controlled workflow to create pre-release tags (alpha/beta/rc) with write-once behavior. * Added stronger enforcement so pre-releases are cut from the correct release line. * **Bug Fixes** * Improved guidance when stable tags are rejected or when base branch info is missing. * Added safeguards to prevent cutting tags from an out-of-date branch tip. * **Documentation** * Updated release process docs, including new tag protection rulesets for `v*` tags. * **Chores** * Pinned multiple CI workflow actions to fixed versions for reliability. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents f91841f + 4a2e439 commit 6b1e170

6 files changed

Lines changed: 247 additions & 17 deletions

File tree

‎.github/workflows/cut-prerelease.yaml‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
name: Cut Pre-release Tag
2+
3+
# Cut a pre-release tag (vX.Y.Z-alpha.N / -beta.N / -rc.N) as the CozyStack CI
4+
# app, so that no human ever pushes a v* tag by hand.
5+
#
6+
# This is the single entry point for creating a pre-release. Stable vX.Y.Z tags
7+
# are never cut here (or by hand) — they are created write-once by
8+
# pull-requests-release.yaml finalize at a promote PR's merge commit. See
9+
# docs/release.md and #2677.
10+
#
11+
# Dispatch from the branch the tag belongs to: `main` for a new minor's
12+
# pre-release (vX.Y.0-rc.N), or `release-X.Y` for a patch line (vX.Y.Z-rc.N).
13+
# The workflow tags that branch's HEAD.
14+
#
15+
# Why a workflow instead of a manual `git push`:
16+
# 1. The tag is pushed with the CI app token. A tag pushed with the default
17+
# GITHUB_TOKEN would NOT trigger tags.yaml (GitHub suppresses workflow
18+
# recursion from GITHUB_TOKEN); the app token is a distinct identity, so
19+
# tags.yaml fires exactly as it does for a maintainer's manual push.
20+
# 2. It pushes `HEAD:refs/tags/<tag>` from the checked-out branch tip, so the
21+
# push event's base_ref is populated — tags.yaml's "Get base branch" step
22+
# needs it to detect main vs release-X.Y.
23+
# 3. It makes CI the sole creator of pre-release tags. Repo rulesets can
24+
# already restrict *stable* tag creation to CI (a "Restrict creations"
25+
# ruleset targeting v* while excluding v*-*), but pre-releases were
26+
# hand-pushed, so they could not be CI-locked. With this workflow as their
27+
# only entry point, admins can extend "Restrict creations" (CI app the sole
28+
# bypass) to *all* of v* — pre-release and stable alike.
29+
30+
on:
31+
workflow_dispatch:
32+
inputs:
33+
tag:
34+
description: "Pre-release tag to cut, e.g. v1.6.0-rc.1 (must be -alpha.N / -beta.N / -rc.N)"
35+
required: true
36+
type: string
37+
38+
concurrency:
39+
# One global lane: two dispatches racing to push overlapping tags would
40+
# confuse the write-once guard. Pre-release cuts are rare, so serialize.
41+
group: cut-prerelease
42+
cancel-in-progress: false
43+
44+
# The tag write happens via the app token, not GITHUB_TOKEN, so the job needs
45+
# only read scope on the default token.
46+
permissions:
47+
contents: read
48+
49+
jobs:
50+
cut:
51+
name: Cut ${{ inputs.tag }}
52+
runs-on: ubuntu-latest
53+
timeout-minutes: 10
54+
55+
steps:
56+
# Pure-input validation first — no token minted, no checkout, so a bad tag
57+
# or wrong dispatch branch fails in seconds.
58+
59+
# Validate the dispatch input against a strict pre-release pattern. A
60+
# stable vX.Y.Z is rejected on purpose: stable tags are cut only by the
61+
# promote flow, at a PR merge commit.
62+
- name: Parse and validate tag
63+
id: parse
64+
env:
65+
TAG: ${{ inputs.tag }}
66+
uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
67+
with:
68+
script: |
69+
const tag = process.env.TAG.trim();
70+
const m = tag.match(/^v(\d+)\.(\d+)\.(\d+)-(alpha|beta|rc)\.(\d+)$/);
71+
if (!m) {
72+
core.setFailed(
73+
`tag '${tag}' must match 'vX.Y.Z-(alpha|beta|rc).N'. ` +
74+
`Stable vX.Y.Z tags are cut by the promote flow, not here.`
75+
);
76+
return;
77+
}
78+
core.setOutput('tag', tag);
79+
core.setOutput('line', `${m[1]}.${m[2]}`); // 1.6
80+
core.setOutput('patch', m[3]); // 0
81+
82+
# Refuse to cut from anything but main or the *matching* release-X.Y line.
83+
# The pushed tag's base_ref (= the dispatch branch) must be one tags.yaml
84+
# accepts, and the branch must actually contain the version being cut.
85+
- name: Validate dispatch branch
86+
env:
87+
REF_NAME: ${{ github.ref_name }}
88+
REF_TYPE: ${{ github.ref_type }}
89+
LINE: ${{ steps.parse.outputs.line }}
90+
PATCH: ${{ steps.parse.outputs.patch }}
91+
run: |
92+
if [ "$REF_TYPE" != "branch" ]; then
93+
echo "::error::Dispatch this workflow from a branch (main or release-X.Y), not a tag or SHA."
94+
exit 1
95+
fi
96+
case "$REF_NAME" in
97+
main)
98+
# From main only a *new minor's* pre-release (vX.Y.0-*) is valid.
99+
# A patch-line pre-release (Z>0) built from main content would land
100+
# on a wrong-tree release-X.Y.Z-rc.N staging branch — it must be cut
101+
# from its own release-X.Y line instead.
102+
if [ "$PATCH" != "0" ]; then
103+
echo "::error::From 'main' only vX.Y.0-* pre-releases may be cut (got patch .$PATCH). Cut v$LINE.$PATCH-* from 'release-$LINE'."
104+
exit 1
105+
fi
106+
;;
107+
release-*)
108+
if [ "release-$LINE" != "$REF_NAME" ]; then
109+
echo "::error::Tag line $LINE does not match dispatch branch '$REF_NAME'. Cut v$LINE.* from 'main' or 'release-$LINE'."
110+
exit 1
111+
fi
112+
;;
113+
*)
114+
echo "::error::Dispatch from 'main' or 'release-X.Y' only. Got '$REF_NAME'."
115+
exit 1
116+
;;
117+
esac
118+
119+
- name: Generate GitHub App token
120+
id: app-token
121+
uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
122+
with:
123+
app-id: ${{ secrets.COZYSTACK_CI_APP_ID }}
124+
private-key: ${{ secrets.COZYSTACK_CI_PRIVATE_KEY }}
125+
owner: cozystack
126+
# Scope the token to this repo only — it never touches other repos.
127+
repositories: ${{ github.event.repository.name }}
128+
129+
# Cutting a release is privileged. workflow_dispatch already requires write
130+
# access to trigger, so this is defense-in-depth: it makes the requirement
131+
# explicit and auditable, and fails closed if that platform default ever
132+
# changes or the job is reached by another path. Reads permission via the
133+
# app token (fails the step if the API errors — fail closed).
134+
- name: Require write access
135+
uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
136+
with:
137+
github-token: ${{ steps.app-token.outputs.token }}
138+
script: |
139+
const { data } = await github.rest.repos.getCollaboratorPermissionLevel({
140+
owner: context.repo.owner,
141+
repo: context.repo.repo,
142+
username: context.actor,
143+
});
144+
// getCollaboratorPermissionLevel's `permission` field returns only
145+
// the legacy roles admin/write/read/none (maintain collapses to
146+
// write, triage to read), so admin+write is the whole "can push" set.
147+
const allowed = ['admin', 'write'];
148+
if (!allowed.includes(data.permission)) {
149+
core.setFailed(
150+
`@${context.actor} has '${data.permission}' access — cutting a pre-release tag ` +
151+
`requires write access to ${context.repo.owner}/${context.repo.repo}.`
152+
);
153+
return;
154+
}
155+
core.info(`@${context.actor}: '${data.permission}' access — authorized.`);
156+
157+
# Minimal checkout — just enough to configure origin with the app-token
158+
# credential (persist-credentials, default on) so the bare push below is
159+
# app-authenticated, and to resolve HEAD. One ref, shallow, no tags.
160+
- name: Check out the dispatched branch
161+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
162+
with:
163+
fetch-depth: 1
164+
token: ${{ steps.app-token.outputs.token }}
165+
166+
- name: Cut and push the pre-release tag
167+
env:
168+
TAG: ${{ steps.parse.outputs.tag }}
169+
REF_NAME: ${{ github.ref_name }}
170+
run: |
171+
# Write-once: the tag must not already exist on origin. Distinguish
172+
# "absent" (git ls-remote --exit-code exits 2) from a transport/auth
173+
# failure (any other non-zero) so an infra blip cannot masquerade as
174+
# "free to create".
175+
set +e
176+
git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1
177+
rc=$?
178+
set -e
179+
if [ "$rc" -eq 0 ]; then
180+
echo "::error::Tag $TAG already exists on origin — pre-release tags are write-once."
181+
exit 1
182+
elif [ "$rc" -ne 2 ]; then
183+
echo "::error::Could not query origin for $TAG (git ls-remote exit $rc) — refusing to proceed."
184+
exit 1
185+
fi
186+
187+
# Stale-tip guard: workflow_dispatch checks out the dispatch-time commit,
188+
# not the branch tip at push time (the gap includes any wait in the
189+
# cut-prerelease concurrency queue). If the branch advanced meanwhile,
190+
# pushing HEAD would tag a stale commit and yield an empty base_ref —
191+
# tags.yaml would then fail, having already burned this write-once name.
192+
# Refuse and ask for a re-run instead.
193+
local_head="$(git rev-parse HEAD)"
194+
# Resolve the remote tip without a pipe masking ls-remote's exit code
195+
# (mirrors the write-once query above): a transport/auth failure must
196+
# not read as "branch not found".
197+
set +e
198+
remote_ls="$(git ls-remote origin "refs/heads/$REF_NAME")"
199+
rc=$?
200+
set -e
201+
if [ "$rc" -ne 0 ]; then
202+
echo "::error::Could not query origin for the tip of '$REF_NAME' (git ls-remote exit $rc) — refusing to proceed."
203+
exit 1
204+
fi
205+
remote_head="$(printf '%s' "$remote_ls" | cut -f1)"
206+
if [ -z "$remote_head" ]; then
207+
echo "::error::Could not resolve the tip of '$REF_NAME' on origin (no such branch?)."
208+
exit 1
209+
fi
210+
if [ "$local_head" != "$remote_head" ]; then
211+
echo "::error::'$REF_NAME' advanced since dispatch ($local_head -> $remote_head). Re-run the workflow to tag the current tip."
212+
exit 1
213+
fi
214+
215+
# Push HEAD straight to a tag ref: no local tag object, non-forced. The
216+
# branch-tip anchoring makes GitHub populate the push event's base_ref
217+
# (tags.yaml's Get-base-branch step requires it); non-forced makes the
218+
# tag write-once at the git layer. tags.yaml takes it from here (build +
219+
# e2e + draft pre-release + staging branch).
220+
git push origin "HEAD:refs/tags/$TAG"
221+
echo "Pushed $TAG at $local_head from '$REF_NAME'."
222+
echo "tags.yaml will now build, e2e, and draft the pre-release."

‎.github/workflows/nightly.yaml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ jobs:
107107
echo "Resolved main build: sha=$sha version=$version packages_ref=$packages_ref"
108108
109109
- name: Checkout source commit
110-
uses: actions/checkout@v4
110+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
111111
with:
112112
ref: ${{ steps.resolve.outputs.sha }}
113113
fetch-depth: 1
@@ -168,7 +168,7 @@ jobs:
168168
packages: write
169169
steps:
170170
- name: Checkout source commit
171-
uses: actions/checkout@v4
171+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
172172
with:
173173
ref: ${{ needs.mirror.outputs.sha }}
174174
fetch-depth: 1
@@ -213,7 +213,7 @@ jobs:
213213
packages: read
214214
steps:
215215
- name: Checkout source commit
216-
uses: actions/checkout@v4
216+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
217217
with:
218218
ref: ${{ needs.mirror.outputs.sha }}
219219
fetch-depth: 1

‎.github/workflows/promote-rc.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ jobs:
137137

138138
# The rc's digest-vendored tree (the staging branch the rc build pushed).
139139
- name: Checkout rc staging branch
140-
uses: actions/checkout@v4
140+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
141141
with:
142142
ref: ${{ steps.parse.outputs.rc_branch }}
143143
fetch-depth: 0

‎.github/workflows/retention.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ jobs:
5252
steps:
5353
- name: Generate GitHub App token
5454
id: app-token
55-
uses: actions/create-github-app-token@v1
55+
uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
5656
with:
5757
app-id: ${{ secrets.COZYSTACK_CI_APP_ID }}
5858
private-key: ${{ secrets.COZYSTACK_CI_PRIVATE_KEY }}

‎.github/workflows/tags.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ jobs:
104104
- name: Reject hand-pushed stable tags
105105
if: steps.check_release.outputs.release_exists == 'false' && steps.tag.outputs.is_stable == 'true'
106106
run: |
107-
echo "::error::Stable tag ${GITHUB_REF#refs/tags/} has no pre-existing draft release. Stable tags come from promote-rc.yaml — push a release candidate (vX.Y.Z-rc.N) and promote it; do not push vX.Y.Z by hand."
107+
echo "::error::Stable tag ${GITHUB_REF#refs/tags/} has no pre-existing draft release. Stable tags are finalized by the promote flow at the merge commit — cut a pre-release (vX.Y.Z-rc.N) with the 'Cut Pre-release Tag' workflow and promote it; do not push vX.Y.Z by hand."
108108
exit 1
109109
110110
# Detect base branch (main or release-X.Y) the tag was pushed from
@@ -116,7 +116,7 @@ jobs:
116116
script: |
117117
const baseRef = context.payload.base_ref;
118118
if (!baseRef) {
119-
core.setFailed(`❌ base_ref is empty. Push the tag via 'git push origin HEAD:refs/tags/<tag>'.`);
119+
core.setFailed(`❌ base_ref is empty — the tag was not pushed at a branch tip. Cut pre-release tags with the 'Cut Pre-release Tag' workflow (workflow_dispatch), which pushes the tag correctly.`);
120120
return;
121121
}
122122
const branch = baseRef.replace('refs/heads/', '');

0 commit comments

Comments
 (0)