auto-merge

type	Skill
name	Auto Merge
category	core
description	Automatically merge open PRs that have passing CI, no blocking reviews, and no conflicts
var
tags	["dev","meta"]

${var} — Repo (owner/repo) to target. If empty, uses every repo in memory/watched-repos.md. Env: AUTO_MERGE_DRY_RUN=1 logs intent without merging. MAX_AUTO_MERGE=N caps merges per run (default 3).

Merge open PRs that are fully green and pass an explicit safety policy. The policy exists because this skill runs autonomously with write access — a bug in the gate is a bug that ships to main.

Read memory/MEMORY.md and memory/watched-repos.md for repos to target. Read the last 2 days of memory/logs/ to avoid re-logging PRs already merged.

Safety policy

A PR merges only when every one of the following holds:

• Author allowlist: author.login is one of dependabot[bot], renovate[bot], github-actions[bot], OR appears under a ## Trusted Authors section in memory/watched-repos.md. No allowlist → only the three bot logins are eligible.
• Size cap: additions + deletions ≤ 500. Override by applying the label auto-merge-large on the PR.
• Base branch: baseRefName is main or master. Refuse any other target.
• Not a fork: isCrossRepository == false (fork CI can be tampered with).
• Not draft: isDraft == false.
• Not already queued: autoMergeRequest == null (avoid fighting GitHub's native auto-merge if a human enabled it).
• No opt-out label: none of {do-not-merge, wip, hold, needs-review, blocked} present.
• Mergeable state: mergeStateStatus == "CLEAN" (this is stricter than mergeable == "MERGEABLE" — CLEAN additionally requires branch-protection gates to be satisfied).
• Reviews: reviewDecision != "CHANGES_REQUESTED".
• Checks: every entry in statusCheckRollup has conclusion in {SUCCESS, NEUTRAL, SKIPPED}. Any FAILURE, TIMED_OUT, CANCELLED, PENDING, or null conclusion disqualifies the PR.
• Retry cap: this PR has been attempted fewer than 3 times. A PR that has hit MERGE_FAIL three times across runs is paused — repeated failure on a CLEAN-looking PR usually means something subtle (a required check that didn't surface, branch-protection drift, token scope drift). Surface it and stop looping.

Steps

0. Bootstrap state — per-PR retry counter lives in memory/topics/auto-merge-state.json:

   mkdir -p memory/topics
   [ -f memory/topics/auto-merge-state.json ] || echo '{"prs":{},"last_run":null}' > memory/topics/auto-merge-state.json
   

   Schema:

   {
     "last_run": "2026-05-23T08:00:00Z",
     "prs": {
       "owner/repo#123": {
         "first_seen": "2026-05-21T10:00:00Z",
         "last_attempt": "2026-05-23T08:00:00Z",
         "attempts": 2,
         "last_outcome": "merge_failed",
         "last_error": "Pull Request is in unstable state"
       }
     }
   }
   

   PR keys are <owner>/<repo>#<number> so state survives multi-repo runs. Cap to 50 most-recent entries (LRU by last_attempt). Validate with jq empty after write; restore from .bak on failure.

1. List open PRs for each watched repo with the full field set:

   gh pr list -R owner/repo --state open --json number,title,author,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,autoMergeRequest,isCrossRepository,labels,additions,deletions,baseRefName
   

Network note

gh authenticates via the workflow's GITHUB_TOKEN — no curl needed. If gh pr merge fails with Resource not accessible by integration, the workflow token lacks merge permission on that repo; log once and notify at most once per 7 days (check memory/logs/ for prior notification) to avoid alert spam.

Constraints

• Never merge a PR whose author is not allowlisted, even if every other gate is green.
• Never bypass the size cap without the explicit auto-merge-large label (set by a human, not a bot).
• Never auto-retry a MERGE_FAIL within the same run — if the first merge attempt fails, log and move on.
• After 3 failed attempts across runs, stop retrying that PR. Surface it once via the retry-cap notification and let the operator investigate.
• Do not modify PR state other than merging (no comments, no label edits, no branch updates).

Running this as an agent-shipping loop

To close the loop on PRs the agent itself opens (from feature, external-feature, self-improve, etc.), add the agent's GitHub identity under a ## Trusted Authors section in memory/watched-repos.md:

## Trusted Authors
- aeon-bot
- claude-code[bot]

Once allowlisted, agent PRs flow through the same safety policy as bot PRs and get auto-merged on green CI. The retry cap protects against runaway behavior on a stuck PR.