PR Auto-Merge Agent

Autonomous PR merge agent. Scans repos for approved + CI-passing PRs and merges them automatically. Supports dry-run mode, squash/merge options, and min-appr...

Security Scan

The skill's code and instructions match its stated purpose (automatically merging GitHub PRs via the gh CLI); nothing in the package attempts unrelated access or hidden exfiltration, though there are small documentation and implementation quirks you should be aware of before enabling it.

Purpose & Capability

The skill only uses the GitHub CLI (gh) via subprocess calls to list and merge PRs and includes a small Python script that implements the described filtering and merge behavior. No unrelated credentials, binaries, or services are requested — this aligns with the stated purpose.

Instruction Scope

Instructions are narrowly scoped to calling gh pr list and gh pr merge; the script does not read arbitrary files or environment variables. Minor issues: the GH Actions example suggests `pip install gh` (the GitHub CLI is usually installed via package managers or GitHub releases, not pip); SKILL.md and function defaults have small inconsistencies (min-approvals default documented as 1 but get_prs_to_merge has a default of 2 in its signature, though main() passes the CLI value). The script enforces only APPROVED reviewDecision, which matches the description.

Install Mechanism

No install spec is provided and the skill is instruction-only with a single, readable script. Nothing is downloaded or executed from external URLs, and included code isn't obfuscated.

Credentials

No environment variables or secrets are requested by the skill itself; it relies on the system-installed gh CLI and the user's authenticated gh session (which must have a token with repo scope). That requirement is proportionate to the task of merging PRs.

Persistence & Privilege

always is false and the skill does not request permanent or elevated platform privileges. It can be invoked by the agent (the normal default), which is expected for an automation skill that may be scheduled or called by an agent.

Assessment

This skill appears to do exactly what it says: it needs a system-installed, authenticated GitHub CLI (gh) with repo permissions and will call gh to list and merge PRs. Before enabling it: 1) Test thoroughly in dry-run mode (default) and on a non-critical repo. 2) Verify how you install the GitHub CLI — the GH Actions example recommending `pip install gh` is misleading; prefer the official gh installers or package managers. 3) Confirm the token used by gh has only the permissions you intend (repo scope is required to merge). 4) Review and adjust min-approvals and squash/merge options, and consider scheduling only for repos you trust the automation on. 5) If you plan to let an autonomous agent run this regularly, restrict which repos it can target and audit runs/logs to avoid unintended merges.

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

# 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

/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

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:

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:

{
  "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