fix(impl-merge): use ADMIN_TOKEN PAT so --admin can bypass main ruleset

[MarkusNeusinger]

Summary

Follow-up to #5521 (which added --admin to gh pr merge). That change alone wasn't enough — verified just now: 3 dispatched merges (#5476, #5480, #5481) all failed identically with:

GraphQL: Repository rule violations found
3 of 3 required status checks are expected.
(mergePullRequest)

Why --admin alone didn't work

The main ruleset's bypass list contains only RepositoryRole admin (mode: pull_request). Default GITHUB_TOKEN runs as github-actions[bot] with write role — not admin — so the API rejects the bypass.

gh api repos/MarkusNeusinger/anyplot/rulesets/10578859 --jq '.bypass_actors'
# [{"actor_id":5,"actor_type":"RepositoryRole","bypass_mode":"pull_request"}]

The fix

Route only the merge step through a repo-admin PAT (ADMIN_TOKEN). All other steps in impl-merge.yml and the rest of the impl-* workflows keep using GITHUB_TOKEN. Bypass scope is therefore exactly one step, not the whole pipeline.

       - name: Merge PR to main (with retry)
         if: steps.check.outputs.should_run == 'true'
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.ADMIN_TOKEN || secrets.GITHUB_TOKEN }}
           PR_NUM: ${{ steps.check.outputs.pr_number }}
           REPOSITORY: ${{ github.repository }}
+          HAS_ADMIN_TOKEN: ${{ secrets.ADMIN_TOKEN != '' }}
         run: |
+          if [ "$HAS_ADMIN_TOKEN" != "true" ]; then
+            echo "::warning::ADMIN_TOKEN secret is not set..."
+          fi

The fallback secrets.ADMIN_TOKEN || secrets.GITHUB_TOKEN and the warning preserve the previous behavior if ADMIN_TOKEN isn't set yet — workflow still runs, fails with the same ruleset error as before, but the log says clearly what's missing instead of an opaque auth error.

Required after merge

1. Create PAT: Settings → Developer settings → Personal access tokens → Fine-grained
   • Repository: anyplot
   • Permissions:
     • Contents: Read+Write
     • Pull requests: Read+Write
     • Administration: Read+Write
     • Metadata: Read
2. Set secret: Settings → Secrets and variables → Actions → New repository secret
   • Name: ADMIN_TOKEN
   • Value: the PAT

Considered alternatives

Option	Verdict
Add github-actions[bot] as bypass actor on ruleset	broader blast radius — every workflow run could bypass main
Remove the 3 required checks from ruleset	weakens protection for human PRs too
Push from impl-generate via PAT so CI triggers naturally	cleanest semantically but needs PAT in 3 workflows + same maintenance overhead
Scope PAT to merge step only (this PR)	smallest blast radius, matches the actual permission gap

Test plan

• Merge this PR
• Create the fine-grained PAT and add as ADMIN_TOKEN repo secret
• Re-dispatch impl-merge.yml for the 3 stuck approved PRs (feat(seaborn): implement marimekko-basic #5476 seaborn, feat(altair): implement marimekko-basic #5480 altair, feat(letsplot): implement marimekko-basic #5481 letsplot)
• Verify each merges successfully on attempt 1 (no ruleset error in run log)
• Verify metadata file created, GCS staging→production promotion done, parent issue gets impl:{library}:done label

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the Impl: Merge GitHub Actions workflow so that the actual merge step can bypass main branch rulesets (required status checks) by using an admin user’s PAT (ADMIN_TOKEN) when available, while keeping the rest of the workflow on GITHUB_TOKEN.

Changes:

• Switch gh authentication for the merge step to prefer secrets.ADMIN_TOKEN over secrets.GITHUB_TOKEN.
• Add a warning in logs when ADMIN_TOKEN is not configured.
• Expand inline documentation around why --admin requires an admin-role token.

[Copilot]

The inline docs and warning refer to a “PAT with admin scope”, but fine-grained PATs don’t have OAuth-style scopes; what matters is that the token belongs to a user with admin role on the repo and has the specific fine-grained permissions needed for gh pr merge --admin. Updating the wording here will reduce confusion when someone sets up ADMIN_TOKEN later.

[Copilot]

Using a repo-admin PAT here significantly increases the blast radius of this workflow: any PR that matches the current conditions (label ai-approved + branch name implementation/*) could be merged to main while bypassing required checks. Consider adding an explicit trust gate before using ADMIN_TOKEN (e.g., require the PR author to be your automation bot and/or assert the PR is not cross-repo and the head repo is the same as github.repository), and fail fast if the gate isn’t met.