PR Auto-Merge Agent#

Autonomous pull request merge tool. Scans GitHub repos for PRs that are approved, CI-passing, and mergeable — then merges them automatically (or reports in dry-run mode).

What It Does#

• Finds all open PRs that are: not drafts + mergeable + CI passing + approved
• Merges them via --squash (default) or --admin --merge
• Supports --dry-run mode to preview what WOULD be merged without making changes
• Configurable minimum approval count
• Pure Python stdlib + gh — zero external dependencies

Prerequisites#

• gh CLI authenticated ( gh auth status)
• Python 3.6+
• Token must have repo scope to merge

Quick Start#

bash

# Preview what would be merged (default — safe)
python3 scripts/auto_merge.py owner/repo

# Actually merge
python3 scripts/auto_merge.py owner/repo --no-dry-run

# Require 2 approvals minimum, squash merge
python3 scripts/auto_merge.py owner/repo --min-approvals 2 --squash

# Scan multiple repos
python3 scripts/auto_merge.py owner/repo1 && python3 scripts/auto_merge.py owner/repo2

Usage as Claude Code Skill#

text

/pr-auto-merger owner/repo --dry-run

The agent will:

1. Fetch all open PRs from the repo via gh pr list --json
2. Filter to approved + CI-passing + mergeable PRs
3. Report in dry-run mode (default), or merge with --no-dry-run

Merge Criteria#

A PR is merged only when ALL of these are true:

• Not a draft ( isDraft: false)
• Mergeable ( mergeable: true)
• All required status checks passing ( statusCheckRollup conclusion: SUCCESS)
• Review decision is APPROVED
• Has at least --min-approvals approvals (default: 1)

Output Format#

text

Scanning owner/repo for mergeable PRs...
[DRY-RUN] Found 3 PR(s) ready to merge:
  #123 — Fix auth middleware (https://github.com/owner/repo/pull/123)
  #456 — Add caching layer (https://github.com/owner/repo/pull/456)
  #789 — Update dependencies (https://github.com/owner/repo/pull/789)

Re-run with --no-dry-run to actually merge.

GitHub Actions Integration#

Drop this into a nightly cron job:

yaml

name: Nightly PR Merge
on:
  schedule:
    - cron: '0 6 * * *'
jobs:
  merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          pip install gh
          gh auth status
          python3 scripts/auto_merge.py owner/repo --no-dry-run --min-approvals 2

Cron Agent Configuration#

For OpenClaw scheduling, configure as:

json

{
  "task": "python3 /path/to/scripts/auto_merge.py owner/repo --no-dry-run",
  "schedule": "0 8 * * 1-5",
  "notify_on": ["failure", "merged"]
}

Architecture#

• scripts/auto_merge.py — Pure Python 3 (stdlib only)
• Uses gh pr list --json for data fetching
• Uses gh pr merge for actual merging
• No pip packages, no external APIs
• Portable: Linux, macOS, Windows (Python + gh)

License#

MIT