bump-dev-version: auto-merge can never complete without WORKFLOW_TOKEN when the repo has required checks

[d-morrison]

bump-dev-version's auto-merge path cannot complete in a repo that has required status checks and gates workflow runs on approval. The bump PR opens, auto-merge is enabled, and then it sits forever.

Observed

ucdavis/bcs#576, opened by the workflow after ucdavis/bcs#575 merged:

• author app/github-actions, mergeable=MERGEABLE, autoMerge=true, mergeStateStatus=BLOCKED
• 1 check run on the head (Analyze (python), from a non-pull_request trigger)
• all six required contexts stuck at "Expected — Waiting for status to be reported"
• every pull_request-triggered run on that SHA reports conclusion: action_required -- the UI shows "13 workflows awaiting approval: Workflows will not run until approved by a user with write permissions."

So the required checks never report, and auto-merge waits on conditions that cannot arrive without a human clicking Approve workflows to run -- on every merge, forever. That is a strictly worse cost than the DESCRIPTION collisions this capability removes: an occasional conflict becomes a guaranteed manual step per merge.

The mechanism is already in place; the documentation misdescribes it

WORKFLOW_TOKEN is already passed to the PR-creating step, not only to checkout:

- name: Open PR if the version moved
  uses: Morrison-Lab/gha/open-sync-pr@v2
  with:
    token: ${{ secrets.WORKFLOW_TOKEN || github.token }}

With it set, the PR is authored by that token's user rather than github-actions[bot], so its pull_request runs are not gated and auto-merge can complete. Without it, they are.

But examples/bump-dev-version.yml says:

Set only if the bot must push to a protected branch; otherwise omit and the push falls back to GITHUB_TOKEN.

That is the narrow reason. The broader one is that without WORKFLOW_TOKEN the auto-merge default is unreachable in any repo with required checks, which is most repos this targets. A consumer reading that line will reasonably omit the secret and get a permanently stuck PR.

Suggested changes

1. Fix the docs, in examples/bump-dev-version.yml and website/reference/bump-dev-version.qmd: state that WORKFLOW_TOKEN is effectively required whenever the repo has required status checks, and say why -- a GITHUB_TOKEN-authored PR either does not trigger workflows or lands in the approval gate.
2. Fail fast on the unreachable combination. When auto-merge: true and no WORKFLOW_TOKEN is present, warn (or fail) at the start rather than opening a PR that can never merge. Right now the failure is silent and only visible days later as a stale open PR -- the shape fail-fast warns about, where the success and failure paths look identical at the moment of the run.

An alternative I would not take

Having the workflow merge its own PR was the first idea considered. It does not avoid the problem: gh pr merge is refused by the same required checks, so it would need a ruleset bypass actor. That weakens branch protection for every rule, not just this one, whereas a scoped PAT weakens nothing -- so the token is the better trade even though it costs a credential to create and rotate.

Pushing the bump straight to main with no PR is the other shape worth considering, and has the same bypass requirement.

[d-morrison]

Claude Code CLI (local session) is working on this — paws off until I'm done.

[d-morrison]

Done — resolved in #433, merged as 59ece54. Unclaiming.