From ad74ebb59972385c20cfbf1ed233ee4684977b14 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Mon, 30 Mar 2026 14:55:21 +0200 Subject: [PATCH 1/2] feat: add auto-merge workflow quality checkpoints and troubleshooting guide Add GH-23 through GH-29 checkpoints covering auto-merge workflow trigger, bot detection, merge flags, and strategy detection. Extend SKILL.md with a new-repo checklist and pitfalls table. Add canonical workflow template to auto-merge-guide.md with design decision rationale. --- skills/github-project/SKILL.md | 25 +++++++ skills/github-project/checkpoints.yaml | 72 +++++++++++++++++++ .../references/auto-merge-guide.md | 47 ++++++++++++ 3 files changed, 144 insertions(+) diff --git a/skills/github-project/SKILL.md b/skills/github-project/SKILL.md index 09ac7b0..10be09f 100644 --- a/skills/github-project/SKILL.md +++ b/skills/github-project/SKILL.md @@ -44,6 +44,31 @@ gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){ Solo maintainer projects MUST have auto-approve. Use `assets/pr-quality.yml.template` and keep `required_approving_review_count >= 1`. See `references/auto-merge-guide.md` for full setup. +### Auto-merge Checklist for New Repos + +Every repository with Dependabot/Renovate should have auto-merge configured: + +1. **Enable auto-merge on repo**: `gh api repos/OWNER/REPO -X PATCH -f allow_auto_merge=true` +2. **Add workflow** `.github/workflows/auto-merge-deps.yml`: + - Trigger: `pull_request_target` (NOT `pull_request`) + - Bot check: `github.event.pull_request.user.login` (NOT `github.actor`) + - Approve: `gh pr review --approve` + - Merge: `gh pr merge --auto $STRATEGY` with dynamic detection +3. **Bot approval**: If branch protection requires reviews, ensure the auto-approve + job handles bot accounts (author_association is NONE for bots) + +See `references/auto-merge-guide.md` for the canonical workflow template. + +### Common Auto-merge Pitfalls + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Bot PRs stuck on REVIEW_REQUIRED | author_association check excludes bots | Add explicit bot login checks | +| Auto-merge queued but never fires | No merge strategy flag | Add dynamic `--auto $STRATEGY` | +| Workflow doesn't trigger on bot PRs | Using `pull_request` trigger | Change to `pull_request_target` | +| Different behavior on PR reruns | Using `github.actor` | Use `github.event.pull_request.user.login` | +| Merge fails in repos with merge queue | Using `gh pr merge --merge` directly | Use `gh pr merge --auto` | + ### Auto-merge Not Working ```bash diff --git a/skills/github-project/checkpoints.yaml b/skills/github-project/checkpoints.yaml index 11b5673..cc63cc9 100644 --- a/skills/github-project/checkpoints.yaml +++ b/skills/github-project/checkpoints.yaml @@ -132,6 +132,41 @@ mechanical: severity: warning desc: "Should migrate from slsa-github-generator to actions/attest-build-provenance (cannot be SHA-pinned)" + # === AUTO-MERGE WORKFLOW CHECKS === + - id: GH-23 + type: command + target: "test -f .github/workflows/auto-merge-deps.yml || test -f .github/workflows/auto-merge.yml" + severity: warning + desc: "Auto-merge workflow should exist for Dependabot/Renovate PRs" + + - id: GH-24 + type: regex + target: .github/workflows/auto-merge-deps.yml + pattern: 'on:\s*\n\s*pull_request_target:' + severity: error + desc: "Auto-merge workflow must use pull_request_target trigger (not pull_request) for bot PR write permissions" + + - id: GH-25 + type: regex + target: .github/workflows/auto-merge-deps.yml + pattern: 'github\.event\.pull_request\.user\.login' + severity: warning + desc: "Auto-merge should check github.event.pull_request.user.login (not github.actor which changes on reruns)" + + - id: GH-26 + type: regex + target: .github/workflows/auto-merge-deps.yml + pattern: '--auto' + severity: warning + desc: "Auto-merge should use gh pr merge --auto (not direct merge) to respect branch protection and merge queues" + + - id: GH-27 + type: regex + target: .github/workflows/auto-merge-deps.yml + pattern: 'gh api.*repos/\$' + severity: info + desc: "Auto-merge should dynamically detect merge strategy from repo settings" + llm_reviews: # === BRANCH PROTECTION + MERGE QUEUE COMPATIBILITY === - id: GH-22 @@ -149,6 +184,43 @@ llm_reviews: severity: error desc: "Verify branch protection rules are compatible with merge queue configuration" + # === AUTO-MERGE CORRECTNESS === + - id: GH-28 + domain: ci + prompt: | + Verify auto-merge workflow end-to-end correctness: + 1. Trigger must be pull_request_target (not pull_request) — bot PRs + need write permissions from the base branch context + 2. Bot detection must use github.event.pull_request.user.login + (not github.actor — actor changes on manual reruns) + 3. Merge command must use --auto flag (respects branch protection, + merge queues, and required checks) + 4. Merge strategy should be dynamically detected from repo settings + via gh api, not hardcoded (repos may enable different strategies) + 5. If repo has branch protection requiring reviews, the workflow must + also approve the PR (gh pr review --approve) before enabling auto-merge + 6. Check for step-security/harden-runner presence + Report specific issues found. + severity: warning + desc: "Verify auto-merge workflow uses correct trigger, bot detection, merge flags, and strategy detection" + + - id: GH-29 + domain: ci + prompt: | + Check if pr-quality.yml or auto-approve workflow correctly handles bot accounts: + 1. Bot accounts (dependabot[bot], renovate[bot]) have author_association + of NONE or CONTRIBUTOR — they are NOT org members/collaborators + 2. If auto-approve checks author_association for OWNER/MEMBER/COLLABORATOR, + it will NEVER approve bot PRs — this is a common misconfiguration + 3. Correct patterns: check user.login explicitly for known bots, + OR use gh api collaborators permission check (which works for apps + with collaborator access) + 4. If branch protection requires approving reviews, bot PRs will be + permanently BLOCKED without a working auto-approve mechanism + Report if bot approval flow has this misconfiguration. + severity: error + desc: "Verify auto-approve workflow correctly handles bot accounts (author_association is NONE for bots)" + # === SUBJECTIVE CHECKS (require LLM judgment) === - id: GH-15 domain: repo-health diff --git a/skills/github-project/references/auto-merge-guide.md b/skills/github-project/references/auto-merge-guide.md index 2315dbc..9c59198 100644 --- a/skills/github-project/references/auto-merge-guide.md +++ b/skills/github-project/references/auto-merge-guide.md @@ -236,6 +236,53 @@ gh pr merge NUMBER --repo OWNER/REPO --auto --merge - `platformAutomerge: true` - Renovate enables auto-merge (uses bypass permissions) - `lockFileMaintenance` - Handles lock file updates via PR (not direct push) +## Canonical Auto-merge Workflow Template + +```yaml +name: Auto-merge dependency PRs + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +permissions: + contents: write + pull-requests: write + +jobs: + auto-merge: + runs-on: ubuntu-latest + if: >- + github.event.pull_request.user.login == 'dependabot[bot]' || + github.event.pull_request.user.login == 'renovate[bot]' + steps: + - name: Approve PR + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh pr review --approve "$PR_URL" + + - name: Enable auto-merge + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + run: | + STRATEGY=$(gh api "repos/$REPO" --jq ' + if .allow_squash_merge then "--squash" + elif .allow_merge_commit then "--merge" + elif .allow_rebase_merge then "--rebase" + else "--merge" end') + gh pr merge --auto "$STRATEGY" "$PR_URL" +``` + +### Key Design Decisions + +- **`pull_request_target`**: Required for bot PRs — `pull_request` runs with read-only tokens for fork-like contexts +- **`user.login`**: Immutable PR author field — `github.actor` changes when humans re-run workflows +- **`--auto`**: Respects branch protection, merge queues, and required checks — direct merge bypasses these +- **Dynamic strategy**: Repos may only allow specific merge methods — hardcoding breaks when config changes + ## Branch Protection for Auto-merge ```bash From 0d12252f2e8bcb8c1ef17042dca67938604566be Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Mon, 30 Mar 2026 15:03:44 +0200 Subject: [PATCH 2/2] fix: trim SKILL.md to stay within 500-word limit Move verbose auto-merge checklist and pitfalls table to a pointer referencing references/auto-merge-guide.md for canonical content. --- skills/github-project/SKILL.md | 33 +++++++++------------------------ 1 file changed, 9 insertions(+), 24 deletions(-) diff --git a/skills/github-project/SKILL.md b/skills/github-project/SKILL.md index 10be09f..7012811 100644 --- a/skills/github-project/SKILL.md +++ b/skills/github-project/SKILL.md @@ -44,30 +44,15 @@ gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){ Solo maintainer projects MUST have auto-approve. Use `assets/pr-quality.yml.template` and keep `required_approving_review_count >= 1`. See `references/auto-merge-guide.md` for full setup. -### Auto-merge Checklist for New Repos - -Every repository with Dependabot/Renovate should have auto-merge configured: - -1. **Enable auto-merge on repo**: `gh api repos/OWNER/REPO -X PATCH -f allow_auto_merge=true` -2. **Add workflow** `.github/workflows/auto-merge-deps.yml`: - - Trigger: `pull_request_target` (NOT `pull_request`) - - Bot check: `github.event.pull_request.user.login` (NOT `github.actor`) - - Approve: `gh pr review --approve` - - Merge: `gh pr merge --auto $STRATEGY` with dynamic detection -3. **Bot approval**: If branch protection requires reviews, ensure the auto-approve - job handles bot accounts (author_association is NONE for bots) - -See `references/auto-merge-guide.md` for the canonical workflow template. - -### Common Auto-merge Pitfalls - -| Symptom | Cause | Fix | -|---------|-------|-----| -| Bot PRs stuck on REVIEW_REQUIRED | author_association check excludes bots | Add explicit bot login checks | -| Auto-merge queued but never fires | No merge strategy flag | Add dynamic `--auto $STRATEGY` | -| Workflow doesn't trigger on bot PRs | Using `pull_request` trigger | Change to `pull_request_target` | -| Different behavior on PR reruns | Using `github.actor` | Use `github.event.pull_request.user.login` | -| Merge fails in repos with merge queue | Using `gh pr merge --merge` directly | Use `gh pr merge --auto` | +### Auto-merge Setup for New Repos + +Every repo with Dependabot/Renovate needs auto-merge. Key requirements: +- Enable `allow_auto_merge` on repo +- Use `pull_request_target` trigger (not `pull_request`) +- Check `user.login` (not `github.actor`) +- Use `gh pr merge --auto` with dynamic strategy + +See `references/auto-merge-guide.md` for the canonical workflow and common pitfalls. ### Auto-merge Not Working