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
📝 WalkthroughWalkthroughA plan document is added specifying a simplified release workflow triggered by ChangesRelease Workflow Plan
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly Related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.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.
Adversarial reviewVerified against Verified
Issues with the proposed
|
Tighten the plan after fresh adversarial review against current release.yml + .changeset/config.json: - Two-job split (prepare / publish-and-tag) preserves least-privilege: prepare holds contents+pull-requests, publish-and-tag holds OIDC. - Add `concurrency:` block — current workflow has it; plan was missing. - Pair `persist-credentials: false` with `commitMode: github-api` so changesets/action commits via API (no remote auth needed, signed by github-actions[bot]). - Move `bun run build` + `bun run test` into publish-and-tag, gated on `should_publish == 'true'` — doc-only main pushes pay only the prepare cost. - Reorder tag/release: `gh release create` creates tag ref + release in one call; closes the orphan-tag failure mode of `git tag` then `gh release create`. - Suppress per-package git tags via `npx changeset publish --no-git-tag`; rely solely on the repo-wide vX.Y.Z. - Document partial-publish recovery, no-changeset push behavior, bot PR caveat (GITHUB_TOKEN PRs don't fire pull_request workflows; pull_request_target / push trigger on changeset-release/main are cheaper alternatives to a scoped App/PAT). - Tighten prerelease regex to anchor on canonical suffixes only. - Reconcile pain-points table to 6 rows (was 7); fix package count 27 (was 28); fix month timestamp (was April 2026). - Phasing: implementation PR ships release.yml + AGENTS.md update together; this plan PR is proposal-only and intentionally does not edit AGENTS.md (which describes the current workflow). Adversarial review: fresh subagent against repo state on this branch flagged 12 issues (1 blocker turned out invalid after CLI verify; remaining items addressed above or accepted as documented tradeoffs). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plans/single-action-release.md`:
- Line 1: The plan file plans/single-action-release.md must be renamed to follow
the date-prefixed convention: create a new file named
plans/YYYY-MM-DD-single-action-release.md using the author date of the first
commit that introduced this plan (replace YYYY-MM-DD with that author date) and
move the content into that file, then delete the old
plans/single-action-release.md and update any references; ensure the filename
matches the slug "single-action-release" exactly and commit the rename so the
repo history reflects the date-prefixed name.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: eea52728-0e2f-45df-aa7b-e79c11f07746
📒 Files selected for processing (1)
plans/single-action-release.md
| @@ -0,0 +1,393 @@ | |||
| # Plan: Single-Action Release | |||
There was a problem hiding this comment.
Rename this plan file to the required date-prefixed format.
plans/single-action-release.md does not follow the required naming convention for significant plans. Please rename it to plans/YYYY-MM-DD-single-action-release.md using the first commit’s author date for this plan (for example, plans/2026-05-04-single-action-release.md if that is the author date).
As per coding guidelines, plans/**/*.md: "When writing plans for significant changes, name them plans/YYYY-MM-DD-<slug>.md using the author date of the first commit that adds the plan".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plans/single-action-release.md` at line 1, The plan file
plans/single-action-release.md must be renamed to follow the date-prefixed
convention: create a new file named plans/YYYY-MM-DD-single-action-release.md
using the author date of the first commit that introduced this plan (replace
YYYY-MM-DD with that author date) and move the content into that file, then
delete the old plans/single-action-release.md and update any references; ensure
the filename matches the slug "single-action-release" exactly and commit the
rename so the repo history reflects the date-prefixed name.
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
Summary by CodeRabbit