plan: collapse release to a single human action#373
Conversation
Captures the cost of the current tag-driven release dance (which we just lived through on the 4.1.0 cut: tag push that didn't open a PR, manually opened version PR #372, force-tag re-push pending) and proposes a single-job push-to-main workflow where the only human action is "merge the version PR." Documents the shape of the rewritten release.yml, what gets removed (force-push tag, separate prepare/publish/github-release jobs, tag-vs-version validation), what stays (OIDC trusted publishing, github-release.yml fallback, publish-check.yml on PRs), and the tradeoffs (lose tag-driven entry; gain control via version-PR cadence). Out of scope: changelog reform (separate plan), prerelease/canary channels. https://claude.ai/code/session_01Jnv99bwWtFWFmsyL7A2cJv
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e3981050bf
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| version="$(node tools/release-version.cjs)" | ||
| tag="v${version}" | ||
| git tag "$tag" | ||
| git push origin "$tag" |
There was a problem hiding this comment.
In the proposed workflow, the checkout step disables credential persistence (persist-credentials: false), but this step later executes git push origin "$tag" when changesets publishes. On GitHub-hosted runners that push will be unauthenticated and fail, which blocks both tag creation and the subsequent GitHub Release step on every real publish run. Either keep checkout credentials enabled for this job or switch to an authenticated API/gh path that creates the tag without git push.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a written plan to simplify TKO’s Changesets-based release process by making “merge the version PR” the only required human action, shifting release.yml to run on main pushes and automating publish + tag + GitHub Release creation.
Changes:
- Documented the current tag-driven release flow and the specific 4.1.0 failure mode.
- Proposed a
push: branches: [main]-triggeredrelease.ymlshape usingchangesets/action’s built-inpublishbehavior. - Outlined tradeoffs, phasing, and a verification checklist for the new flow.
| - uses: actions/checkout@v6 | ||
| with: | ||
| fetch-depth: 0 # changesets needs full history | ||
| persist-credentials: false | ||
|
|
There was a problem hiding this comment.
In the proposed workflow snippet, actions/checkout is configured with persist-credentials: false, but later steps push a git tag to origin. With credentials not persisted, git push origin "$tag" will fail unless you add separate git authentication/remote configuration (or avoid git push by letting gh release create create the tag).
| git tag "$tag" | ||
| git push origin "$tag" | ||
| prerelease="" | ||
| case "$version" in *-alpha*|*-beta*|*-rc*) prerelease="--prerelease";; esac | ||
| gh release create "$tag" \ | ||
| --target "$GITHUB_SHA" \ | ||
| --title "TKO ${version}" \ | ||
| --generate-notes \ | ||
| $prerelease |
There was a problem hiding this comment.
The proposed “Tag repo + create GitHub release” step isn’t idempotent: git tag "$tag" fails if the tag already exists, and gh release create fails if the release exists (e.g., reruns, partial failures, or manual backfill). Consider reusing the existing github-release workflow’s safety checks (view existing release/tag, verify target SHA, and skip when already correct) so retries are safe.
| git tag "$tag" | |
| git push origin "$tag" | |
| prerelease="" | |
| case "$version" in *-alpha*|*-beta*|*-rc*) prerelease="--prerelease";; esac | |
| gh release create "$tag" \ | |
| --target "$GITHUB_SHA" \ | |
| --title "TKO ${version}" \ | |
| --generate-notes \ | |
| $prerelease | |
| target_sha="${GITHUB_SHA}" | |
| local_tag_sha="$(git rev-parse -q --verify "refs/tags/$tag^{commit}" 2>/dev/null || true)" | |
| remote_tag_sha="$(git ls-remote --tags origin "refs/tags/$tag" | awk '{print $1}' | head -n1)" | |
| if [ -n "$local_tag_sha" ] && [ "$local_tag_sha" != "$target_sha" ]; then | |
| echo "Existing local tag $tag points to $local_tag_sha, expected $target_sha" >&2 | |
| exit 1 | |
| fi | |
| if [ -n "$remote_tag_sha" ] && [ "$remote_tag_sha" != "$target_sha" ]; then | |
| echo "Existing remote tag $tag points to $remote_tag_sha, expected $target_sha" >&2 | |
| exit 1 | |
| fi | |
| if [ -z "$local_tag_sha" ] && [ -z "$remote_tag_sha" ]; then | |
| git tag "$tag" "$target_sha" | |
| git push origin "$tag" | |
| else | |
| echo "Tag $tag already exists at the expected SHA; skipping tag creation." | |
| fi | |
| prerelease="" | |
| case "$version" in *-alpha*|*-beta*|*-rc*) prerelease="--prerelease";; esac | |
| release_json="$(gh release view "$tag" --json tagName,targetCommitish 2>/dev/null || true)" | |
| if [ -n "$release_json" ]; then | |
| release_tag="$(printf '%s' "$release_json" | jq -r '.tagName')" | |
| release_target="$(printf '%s' "$release_json" | jq -r '.targetCommitish')" | |
| if [ "$release_tag" != "$tag" ]; then | |
| echo "Existing release lookup returned unexpected tag $release_tag for $tag" >&2 | |
| exit 1 | |
| fi | |
| if [ "$release_target" != "$target_sha" ]; then | |
| echo "Existing release $tag targets $release_target, expected $target_sha" >&2 | |
| exit 1 | |
| fi | |
| echo "Release $tag already exists at the expected target; skipping release creation." | |
| else | |
| gh release create "$tag" \ | |
| --target "$target_sha" \ | |
| --title "TKO ${version}" \ | |
| --generate-notes \ | |
| $prerelease | |
| fi |
| jobs: | ||
| release: | ||
| permissions: | ||
| contents: write # tags + GitHub release | ||
| pull-requests: write # opens version PR | ||
| id-token: write # npm OIDC | ||
|
|
There was a problem hiding this comment.
Collapsing to a single job means the job needs both contents: write (tags/releases) and id-token: write (npm OIDC) during the entire run (including checkout/install/build). That’s a meaningful increase in token blast radius vs the current split-job, least-privilege design in .github/workflows/release.yml. Either call out this security tradeoff explicitly in the plan and add mitigations (e.g., keep separate jobs, use environments/required reviewers for publish, etc.), or retain the least-privilege separation.
| | Current step | Time/risk cost | | ||
| |---|---| | ||
| | Push initial tag | Trivial, but obscures intent ("am I starting a release or testing CI?") | | ||
| | Wait for action to maybe-open a PR | Action is flaky under tag triggers (see above) | |
There was a problem hiding this comment.
The pain-points table is written with a double leading pipe (||), which renders as an empty first column in Markdown. If the intent is a 2‑column table, switch those rows to a single leading pipe (| Current step | … |, |---|---|, etc.) so it renders correctly in GitHub.
Summary
Captures the cost of TKO's current tag-driven release flow — which we just lived through on the 4.1.0 cut — and proposes collapsing it to a single human action: merge the version PR.
Why now
The 4.1.0 cut required:
v4.1.0changesets/action(which silently skipped PR creation under the tag-push trigger — known wrinkle, branch namechangeset-release/refs/tags/v4.1.0is the symptom)Five out of six steps are admin or latency. The two with maintainer judgment (review and merge) are buried in the noise. That cuts directly against the Dark Factory thesis — a single time-constrained maintainer with AI agents shouldn't be pushing tags twice and worrying about whether they're on the right commit.
Proposed shape
release.ymlonpush: branches: [main](the canonical changesets pattern).prepare-release/publish/github-release).changesets/action's built-inpublishinput runsnpx changeset publishautomatically when there are no pending changesets and setsoutputs.published.vX.Y.Zfromtools/release-version.cjs, creates the tag and GitHub Release. No more force-push tag dance, no more tag-vs-version validation.Tradeoffs
github-release.ymlalready exists as a manual backfill workflow.Out of scope
next).Test plan
release.ymland the 4.1.0-cut experiencehttps://claude.ai/code/session_01Jnv99bwWtFWFmsyL7A2cJv
Generated by Claude Code