Skip to content

ci(release): move the major tag only to an immutable release #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
soulbah merged 1 commit into from
Oct 8, 2026
Merged

ci(release): move the major tag only to an immutable release #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,16 @@ jobs:
fi
jq -e '.draft == false' <<<"$release" >/dev/null || fail "$tag is still a draft."
[[ "$(gh api "repos/$GITHUB_REPOSITORY/commits/$tag" --jq .sha)" == "$GITHUB_SHA" ]] || fail "$tag does not name $GITHUB_SHA."
# The repository enforces immutable releases. GitHub can report the lock a few seconds after publication.
for attempt in 1 2 3 4 5 6; do
jq -e '.immutable == true' <<<"$release" >/dev/null && break
[[ "$attempt" -lt 6 ]] ||
fail "$tag is published but not immutable, so the major tag was not moved. Enable release immutability, delete this release (keep its tag) and rerun: the run republishes it immutable."
sleep $((attempt * 5))
release="$(gh api "repos/$GITHUB_REPOSITORY/releases/tags/$tag")"
done
echo "tag=$tag" >> "$GITHUB_OUTPUT"
echo "Published $(jq -r .html_url <<<"$release") at \`$GITHUB_SHA\` (immutable: $(jq -r '.immutable // false' <<<"$release"))." >> "$GITHUB_STEP_SUMMARY"
echo "Published immutable $(jq -r .html_url <<<"$release") at \`$GITHUB_SHA\`." >> "$GITHUB_STEP_SUMMARY"

- name: Point the major tag at this release
if: steps.release.outputs.tag != ''
Expand Down
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,9 @@ A release is a separate maintainer dispatch on `main`:
major version. A promotion carrying only `chore`, `ci`, `docs`, `style`,
`test`, or `refactor` commits releases nothing.
3. The same run points the major tag (`v1` for `v1.x.y`) at the new release.
It only moves forward; rerunning resumes an interrupted release. See
`docs/adr/007-promoted-releases-and-major-tags.md`.
It only moves forward, and only once GitHub reports the release immutable
(the repository enforces immutable releases). Rerunning resumes an
interrupted release. See `docs/adr/007-promoted-releases-and-major-tags.md`.

Never create, move, or delete a tag or release by hand. Published references are
what other people's workflows execute; correct a mistake with a new release.
Expand Down
3 changes: 3 additions & 0 deletions docs/adr/007-promoted-releases-and-major-tags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,9 @@ under default rules is `v1.0.0`, which matches the public `@v1` contract.
creates its own tag; `v0` is never maintained. Version tags never move.
- A rerun resumes: if semantic-release pushed a tag without its release, the
run publishes the release for that tag, then moves the major tag.
- The repository enforces immutable releases, so a published `vX.Y.Z` tag
and its release can no longer change. The run moves the major tag only
after GitHub reports the new release immutable.
- `publish-v1.yml` is removed. The existing `v1` advances to `v1.0.0` through
the first release run.
- Running `release.yml` remains an owner decision.
Expand Down
Loading