Changeset PRs Need a Checked Auto-Release Gate

Problem

Changeset PRs create a follow-up [Release] Version packages PR after merge. When the author wants that release PR to merge automatically, the intent needs to live on the original PR and be enforceable by workflow automation.

Symptoms

• The release PR opens successfully, but still needs a human to merge it.
• Reviewers cannot tell whether the original author wanted immediate release.
• A comment-only or template-only checkbox records intent but does not make the release PR merge itself.

What Didn't Work

• Putting a static checkbox in the PR template would show up on every PR, including PRs with no changeset.
• Adding only a comment would be easy to miss and harder to treat as the source of truth.
• Auto-merging the release PR with the default GITHUB_TOKEN is risky because GitHub suppresses workflow runs triggered by that token, which can prevent the publish workflow from firing after the release PR merge.
• Skipping CI for [Release] Version packages PRs leaves the required CI check skipped, so GitHub auto-merge stays blocked.

Solution

Use a managed PR-body checkbox plus release workflow enforcement:

1. Add a pull_request_target workflow that checks out base code, reads PR file names through the GitHub API, and upserts the checkbox only when the PR contains a real .changeset/*.md file.
2. Default patch-only changeset PRs to checked, and default PRs with any minor or major changeset to unchecked.
3. Preserve the checked state when the user edits the checkbox.
4. In the release workflow, inspect the merged PR associated with the push to main.
5. If the merged PR has a checked managed checkbox and a changeset file, enable auto-merge on the generated release PR.
6. Use API_TOKEN_GITHUB for the merge path so the follow-up publish workflow can run.
7. Do not add the managed checkbox to PRs whose title contains Version packages.
8. Let required checks run on release PRs; a skipped required check is not a mergeable check.

env:
  GH_TOKEN: ${{ secrets.API_TOKEN_GITHUB }}
run: |
  if [[ -z "${GH_TOKEN}" ]]; then
    echo "API_TOKEN_GITHUB is required so the auto-merged release PR can trigger publish workflows."
    exit 1
  fi

  gh pr merge "$RELEASE_PR" --auto --squash --delete-branch

Why This Works

The PR body is the right place for human release intent because it is visible before merge and preserved with the PR. The workflow is the right place for enforcement because it can prove the PR actually has a changeset and can connect the merged source PR to the release PR generated by changesets/action.

Using the PAT is the critical bit. The release PR merge must create the normal push event that runs the publish path.

Generated release PRs are the output of that intent, not a new decision point. They should not get their own Auto release checkbox. If branch rules require CI, release PRs need a successful CI run rather than a skipped one.

Prevention

• Keep dynamic release intent in a managed PR-body block, not only in comments.
• Default low-risk patch release PRs to checked, but make minor and major releases an explicit opt-in.
• Exclude PR titles containing Version packages from checkbox management.
• Do not skip checks that branch rules require for release PR auto-merge.
• For pull_request_target, only run trusted base-repo code and read untrusted PR data through the GitHub API.
• Do not use default GITHUB_TOKEN for workflow-triggering release merges.
• Add helper tests for checkbox preservation, changeset-file detection, and ignoring stray checkbox text outside the managed block.

Related Issues

• docs/solutions/workflow-issues/2026-03-26-template-sync-fallback-prs-must-close-after-later-success.md