ghprmerge

Purpose

ghprmerge solves the problem of merging many similar pull requests across a GitHub organization. When you have dozens or hundreds of repositories with Dependabot (or similar automated) PRs, manually reviewing and merging each one becomes impractical.

The tool provides four subcommands:

• merge — merge ready pull requests across an organization
• rebase — update out-of-date PR branches across an organization
• close — close matching pull requests, optionally deleting their source branches after a successful close
• report — scan open PRs and group them by source branch name, helping you identify common updates that span multiple repositories

The built-in CLI help (ghprmerge --help) includes these subcommand descriptions so users and automation agents can quickly select the correct mode without opening external documentation.

For every execution mode, place the subcommand first, then its flags (for example, ghprmerge merge --org myorg --repo repo1 ...). GITHUB_ORG remains available as the default when --org is omitted.

Safety Model

ghprmerge is designed to be safe by default:

1. Explicit subcommands - Use merge to merge PRs, rebase to update branches, close to close unwanted PRs, or report for a read-only overview
2. Confirmation mode - Use --confirm with merge, rebase, or close to preview what would happen before executing
3. Strict readiness checks - A PR is only considered ready if:
   • All check runs have a successful conclusion (including non-required checks), or no checks are configured at all
   • All commit status contexts are successful, or no statuses are configured at all
   • No merge conflicts
   • Branch is fully up to date with the default branch (unless --skip-rebase is used with merge)
4. Repository workers - --workers <n> controls concurrent repository processing (default: GHPRMERGE_WORKERS or 1; the flag overrides the environment). A single coordinator serializes output and progress updates.
5. No local checkout - All operations use the GitHub API

Non-Goals

• No local git operations or repository checkouts
• Repository concurrency is bounded by --workers; PRs in each repository remain sequential
• No creating or approving pull requests
• No modifying repository settings

Execution Flow

merge command

scan → evaluate → merge → report

For each repository (up to --workers repositories at a time; PRs within each repository remain sequential):

1. Fetch repository metadata including default branch (archived repositories are skipped)
2. Enumerate candidate PRs matching --source-branch patterns (can be specified multiple times)
3. For each candidate PR:
   • Evaluate readiness (checks, conflicts, branch status)
   • If PR is valid: attempt merge, waiting as needed to satisfy --min-merge-delay between merge requests
   • With --skip-rebase: attempt merge even if branch is behind
   • Record result immediately
4. Show progress bar during scanning. The merge delay is applied only immediately before a merge request; it is not a scanning delay.
   • Stream action results as complete repository blocks when each repository finishes with the progress bar continuing below
   • With --verbose, stream each repository result as soon as it is known
   • With --confirm, scan without actions, prompt, then stream each action result during execution
5. Print condensed summary

rebase command

scan → evaluate → rebase → report

For each repository (up to --workers repositories at a time; PRs within each repository remain sequential):

1. Fetch repository metadata including default branch (archived repositories are skipped)
2. Enumerate candidate PRs matching --source-branch patterns (can be specified multiple times)
3. For each candidate PR:
   • Evaluate readiness (checks, conflicts, branch status)
   • Update branch if behind
   • Record result immediately
4. Show progress bar during scanning
   • Stream action results as complete repository blocks when each repository finishes with the progress bar continuing below
   • With --verbose, stream each repository result as soon as it is known
   • With --confirm, scan without actions, prompt, then stream each action result during execution
5. Print condensed summary

close command

scan → evaluate → close → optionally delete source branch → report

For each repository (up to --workers repositories at a time; PRs within each repository remain sequential):

1. Fetch repository metadata including default branch (archived repositories are skipped)
2. Enumerate candidate PRs matching --source-branch patterns (can be specified multiple times)
3. For each candidate PR:
   • Consider only open, non-draft PRs targeting the default branch; checks, mergeability, and branch currency do not affect close eligibility
   • Close the PR
   • If --delete-source-branch is set and the close succeeds, delete its source branch from the PR’s head repository, including a fork when applicable
   • Record the close and any deletion result immediately
4. Show progress bar during scanning
   • Stream action results as complete repository blocks when each repository finishes with the progress bar continuing below
   • With --verbose, stream each repository result as soon as it is known
   • With --confirm, scan without actions, prompt, then stream each action result during execution
5. Print condensed summary

report command

scan → collect open PRs → group by branch name → filter → sort → display

1. Discover repositories using the same logic as the other subcommands
2. Collect all open, non-draft PRs targeting the default branch
3. Group PRs by exact source branch name
4. Filter by --source-branch-prefix if set
5. Exclude groups smaller than --min-group-size (default: 2)
6. Sort by descending count, then ascending branch name
7. Display results according to --verbosity level or as JSON with --json

Contents

• USAGE.md - Complete command-line reference with flag table
• MERGE.md - Merge subcommand details
• REBASE.md - Rebase subcommand details
• CLOSE.md - Close subcommand details
• REPORT.md - Report subcommand details
• EXAMPLES.md - Practical example commands and workflows
• INSTALL.md - Installation instructions

Independent status and rebase outcomes

Report evaluates checks and branch freshness independently, including branch comparisons when checks fail or are pending. Text displays both conditions; JSON adds checks, branchStatus, and behindBy alongside the existing primary status.

Rebase updates all eligible PRs matching any source pattern, sequentially within a repository. Up-to-date branches are reported as no rebase needed, preserving actual check status. Successful submissions are rebase requested; completion is not verified. The summary distinguishes requests submitted from branches already up to date. The same classification applies during confirmation scans and execution.

Merge and close choose the first supplied pattern that matches an eligible PR after author filtering. Other matching PRs remain visible as explicit skips and are included in candidate counts.