fix(release): pin build dispatch to the tag, fix release-branch naming

[EtienneLescot]

Two bugs in the release pipeline, both found while cutting v1.7.0-rc.1 (the first RC under the release-branch freeze, so neither path had ever run).

1. Build dispatched on the wrong ref

prerelease.yml ran gh workflow run build.yml without --ref, so the build dispatched on the default branch (main), where package.json is still the previous stable version. The RC bump lives only on the release branch, so build.yml's publish guard rejected it:

##[error]package.json version 1.6.0 does not match 1.7.0-rc.1 from tag v1.7.0-rc.1

No release was created, and the installers were stamped 1.6.0. Fixed by pinning --ref "${RC_TAG}" (and --ref "${STABLE_TAG}" in promote.yml, which only worked before because the preceding main-merge happened to leave main at the stable version).

2. Release branch naming breaks promote and defeats the freeze

• prerelease.yml created release/v${PRERELEASE} → release/v1.7.0-rc.1
• promote.yml resolves release/v${STABLE_VERSION} → release/v1.7.0

That branch doesn't exist, so promote would have failed at git fetch origin release/v1.7.0.

Worse: each re-cut created a new branch off main and force-deleted the remote branch first. Cutting rc.2 would therefore sweep in anything landed on main and destroy the cherry-picks on the rc.1 branch — silently defeating the freeze the contract exists to guarantee.

Fixed by using one branch per stable version (release/vX.Y.Z), created at rc.1 and reused for later RCs: fetch + check out when it exists, branch from the dispatched ref when it doesn't, never delete. The package.json bump moved into the same step so the version is written after the correct branch is checked out.

Verification

• build.yml --ref v1.7.0-rc.1 (equivalent of fix 1) ran green on Windows/macOS(arm64+x64)/Linux and published v1.7.0-rc.1 with 6 assets.
• Fix 2 is exercised by the next cut (rc.2), which will create release/v1.7.0 and let promote resolve it.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved prerelease (RC) branch and prerelease version handling so release candidates are cut and recut reliably from the same frozen release snapshot.
  • Ensured build workflows are dispatched against the intended RC and promoted stable tags, using the matching package version to avoid stale default-branch state.
  • Updated release tagging/build behavior during promotion to prevent mismatched version checks.

[coderabbitai]

📝 Walkthrough

Walkthrough

Release workflows now create or reuse frozen prerelease branches, tag RCs from the target release branch, and dispatch build.yml from the matching RC or stable tag.

Changes

Release workflow snapshot handling

Layer / File(s)	Summary
Create and tag the frozen prerelease branch .github/workflows/prerelease.yml	Prerelease cuts create release/v${NEXT} from the dispatched ref for rc.1, reuse it for later RCs, update package.json, and push RC tags from that branch.
Pin release workflow dispatches .github/workflows/prerelease.yml, .github/workflows/promote.yml	Build dispatches use ${RC_TAG} for prereleases and ${STABLE_TAG} for promotions; comments document the tag-specific checkout requirement.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is informative but misses most required template sections, including Summary, Related issue, Type of change, and release impact.	Add the missing template sections and label the current Verification section as Testing, with a related issue entry and change/release classifications.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title matches the main changes: pinning build dispatches to release tags and fixing release-branch naming.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/prerelease-version-tag-ee96ae

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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