ci: auto-merge Dependabot patch/minor PRs

[TexasCoding]

Summary

Adds a workflow that auto-enables squash-merge on Dependabot PRs for patch and minor updates. Major bumps are left for human review.

Why

Six Dependabot PRs (#145–#150) piled up because there was no auto-merge wiring. All had green CI but were waiting for a human to click merge. This workflow handles the routine patch/minor cases so they flow through automatically.

Mechanics

• Triggers on pull_request events from dependabot[bot] only.
• Uses dependabot/fetch-metadata@v2.4.0 (SHA-pinned) to extract the semver update type.
• Calls gh pr merge --auto --squash, which queues the merge until required status checks pass (test 3.12, test 3.13, drift-check). Failed checks → no merge.
• Major updates: skipped. Human reviews and merges manually.

Why no auto-approve step

Branch protection on main requires status checks but not reviewers (solo-maintainer repo). gh pr merge --auto only needs CI green to fire — no review step needed.

Test plan

• Workflow appears in Actions tab on first PR after merge.
• Next patch/minor Dependabot PR: auto-merge enabled, fires on CI green.
• Next major Dependabot PR: no auto-merge enabled (still queued for human review).

🤖 Generated with Claude Code

[claude]

Code Review — PR #152: Dependabot Auto-Merge Workflow

Overview

Adds .github/workflows/dependabot-auto-merge.yml to auto-enable squash-merge on Dependabot PRs for patch and minor version updates. Major bumps are excluded from automation. The approach is minimal and well-motivated — six queued PRs with green CI is exactly the problem this solves.

---

What's Good

• SHA-pinned action — dependabot/fetch-metadata@08eff52... with the # v2.4.0 comment is the right way to pin third-party actions. Prevents supply-chain surprises while keeping the version readable.
• Minimal permissions — contents: write + pull-requests: write with nothing else is correctly scoped.
• if actor guard — Filtering on github.actor == 'dependabot[bot]' is a solid safety net so the job skips entirely on non-Dependabot triggers.
• Env-var PR URL — Using PR_URL via env: instead of inline ${{ ... }} in the run: shell command avoids potential injection if the URL were ever user-controlled. Good habit even though it's unnecessary here.

---

Concern: pull_request trigger may produce a read-only token for Dependabot PRs

This is the main issue worth resolving before this workflow goes live.

GitHub restricts GITHUB_TOKEN to read-only permissions for workflows triggered by Dependabot via the pull_request event, regardless of what the permissions: block declares. This is a hardened security posture GitHub introduced to protect against dependency confusion attacks. The effect is that gh pr merge --auto --squash will fail with a 403/permission error even though the workflow runs and the permissions block looks correct.

Recommended fix: use pull_request_target instead of pull_request.

on:
  pull_request_target:
    types: [opened, reopened, synchronize]

pull_request_target runs in the context of the base branch with write-capable tokens, which is why GitHub recommends it for Dependabot workflows that need write access. The usual pull_request_target risk (untrusted code running with repo secrets) doesn't apply here because:

1. The job only executes gh pr merge --auto, which carries no secret-exfiltration surface.
2. The if: github.actor == 'dependabot[bot]' guard means arbitrary contributors can't trigger the job.

GitHub's own documentation for Dependabot Actions explicitly recommends pull_request_target for scenarios requiring write access: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions#enable-auto-merge-on-a-pull-request

---

Minor Suggestions

1. Explicit event types on the trigger — The default pull_request (or pull_request_target) fires on opened, synchronize, and reopened. Being explicit makes intent clear and avoids accidental firings if GitHub ever changes defaults:

   on:
     pull_request_target:
       types: [opened, reopened, synchronize]

2. Workflow-level vs job-level permissions — The permissions: block is at the workflow level, meaning it applies to all jobs. With only one job here that's fine, but if a second job is ever added, permissions will be over-granted by default. Consider moving the block under jobs.auto-merge: for tighter scoping:

   jobs:
     auto-merge:
       if: github.actor == 'dependabot[bot]'
       runs-on: ubuntu-latest
       permissions:
         contents: write
         pull-requests: write

---

Test Plan Additions

The existing test plan is good. Suggest adding one more check:

• Confirm in the Actions run log that gh pr merge --auto --squash exits 0 (not a silent 403). The workflow can appear green while the merge step silently errors if the token lacks write access.

---

Summary

The workflow is well-structured and the intent is exactly right. The pull_request → pull_request_target swap is the only change needed before this is production-safe. Everything else is polish.