Report Command

The report subcommand scans open pull requests across repositories in a GitHub organization and groups them by source branch name. It is a read-only command — no mutations are performed.

Synopsis

ghprmerge report --org <organization> [flags]

The report subcommand discovers repositories using the same logic as the merge and rebase subcommands, collects all open PRs (non-draft, targeting the default branch), and groups them by exact source branch name. Groups are sorted by descending PR count, with ties broken by ascending branch name. This is useful for identifying batches of related PRs (e.g., Dependabot updates for the same dependency) that can be merged or rebased together.

Required Setup

Flag	Default	Description
`--org <organization>`	`GITHUB_ORG` env	GitHub organization to scan. Required unless `GITHUB_ORG` is set.

Filtering and Execution Controls

Flag	Default	Description
`--repo <repository>`	-	Limit scanning to an exact repository name in the organization; may be repeated.
`--author <login>`	`GHPRMERGE_AUTHOR` env	Include only PRs opened by this GitHub login.
`--repo-limit <n>`	`0`	Process at most `n` repositories; `0` means unlimited.
`--workers <n>`	`GHPRMERGE_WORKERS` env or `1`	Maximum concurrent repository workers; must be at least `1`. Available on all subcommands.

Output Controls

All output flags except --verbose can be used with report.

Flag	Default	Description
`--json`	`false`	Output structured JSON instead of human-readable text.
`--no-color`	`false`	Disable ANSI color output.
`--no-progress`	`false`	Suppress progress-bar output for CI or scripts.

Report Flags

These flags are placed after report.

Flag	Default	Description
`--source-branch-prefix`	-	Comma-separated list of branch prefixes to include in report
`--min-group-size`	`2` (`GHPRMERGE_MIN_GROUP_SIZE` env)	Minimum number of PRs in a group to include in report
`--verbosity`	`standard`	Report output verbosity: `brief`, `standard`, or `verbose`

Flag restrictions: The flags --source-branch, --skip-rebase, --confirm, and --verbose cannot be used with the report subcommand.

Behavior

The report subcommand processes repositories with --workers workers (default: one) using the same discovery logic as the merge and rebase subcommands:

Discover repositories: Enumerate repositories in the organization, respecting --repo and --repo-limit filters. Archived repositories are excluded.
Collect open PRs: For each repository, list all open pull requests that are not drafts and target the default branch.
Group by source branch: Group collected PRs by their exact head branch name.
Filter by prefix: If --source-branch-prefix is set, only groups whose branch name starts with one of the specified prefixes are included.
Filter by group size: Groups with fewer PRs than --min-group-size (default: 2) are excluded.
Sort: Groups are sorted by descending PR count. Ties are broken by ascending branch name.
Evaluate status: Each PR is evaluated for both check status and branch status relative to the default branch, even when checks fail or are pending.

No mutations are performed. The report subcommand is entirely read-only. It never merges, rebases, or comments on pull requests.

Verbosity

The --verbosity flag controls the level of detail in text output. It accepts three values:

`brief`

Displays only the branch name and PR count for each group:

dependabot/go_modules/foo-1.2.3 (3 PRs)
dependabot/npm_and_yarn/bar-2.0.0 (2 PRs)

`standard` (default)

Displays the branch name, count, and for each PR: the repository name, PR number, and status:

dependabot/go_modules/foo-1.2.3 (3 PRs)
  repo-a     #123  all checks passing; up to date
  repo-b     #456  all checks passing; 6 commits behind
  repo-c     #789  checks pending; up to date

dependabot/npm_and_yarn/bar-2.0.0 (2 PRs)
  repo-a     #124  all checks passing; up to date
  repo-d     #321  all checks passing; conflict

`verbose`

Includes everything from standard plus the PR title:

dependabot/go_modules/foo-1.2.3 (3 PRs)
  repo-a     #123 Bump foo from 1.2.2 to 1.2.3 all checks passing; up to date
  repo-b     #456 Bump foo from 1.2.2 to 1.2.3 all checks passing; 6 commits behind
  repo-c     #789 Bump foo from 1.2.2 to 1.2.3 checks pending; up to date

dependabot/npm_and_yarn/bar-2.0.0 (2 PRs)
  repo-a     #124 Bump bar from 1.9.0 to 2.0.0 all checks passing; up to date
  repo-d     #321 Bump bar from 1.9.0 to 2.0.0 all checks passing; conflict

The --verbosity flag only affects text output. JSON output always includes all fields regardless of the verbosity setting.

JSON Output

With --json, the report subcommand outputs structured JSON. The schema is the same regardless of --verbosity:

{
  "groups": [
    {
      "sourceBranch": "dependabot/go_modules/foo-1.2.3",
      "count": 3,
      "pullRequests": [
        {
          "repository": "repo-a",
          "number": 123,
          "status": "passing",
          "checks": "all checks passing",
          "branchStatus": "up to date",
          "behindBy": 0,
          "title": "Bump foo from 1.2.2 to 1.2.3",
          "url": "https://github.com/myorg/repo-a/pull/123"
        },
        {
          "repository": "repo-b",
          "number": 456,
          "status": "needs-rebase",
          "checks": "all checks passing",
          "branchStatus": "needs-rebase",
          "behindBy": 6,
          "title": "Bump foo from 1.2.2 to 1.2.3",
          "url": "https://github.com/myorg/repo-b/pull/456"
        },
        {
          "repository": "repo-c",
          "number": 789,
          "status": "checks pending",
          "checks": "checks pending",
          "branchStatus": "up to date",
          "behindBy": 0,
          "title": "Bump foo from 1.2.2 to 1.2.3",
          "url": "https://github.com/myorg/repo-c/pull/789"
        }
      ]
    }
  ]
}

Each group contains:

Field	Type	Description
`sourceBranch`	string	The exact head branch name shared by PRs in this group
`count`	number	The number of PRs in the group
`pullRequests`	array	List of PRs in the group

Each pull request contains:

Field	Type	Description
`repository`	string	The repository name (without the organization prefix)
`number`	number	The pull request number
`status`	string	The primary evaluated status (see Status Values)
`checks`	string	`all checks passing`, `checks failing`, `checks pending`, `no checks configured`, or `error`
`branchStatus`	string	`up to date`, `needs-rebase`, `conflict`, or `error`
`behindBy`	number	Commits behind the base; only meaningful when `branchStatus` is not `error`
`title`	string	The pull request title
`url`	string	The full URL to the pull request on GitHub

Status Values

Each PR retains a primary status for compatibility. Failed or pending checks take precedence; otherwise conflicts and behind branches take precedence over passing/no-checks status. Independent fields expose simultaneous conditions:

Status	Description
`passing`	All checks passing and branch is up-to-date with the default branch
`needs-rebase`	Branch is behind the default branch
`conflict`	PR has merge conflicts
`checks failing`	One or more required checks have failed
`checks pending`	Checks are still running
`no checks configured`	No status checks are configured for the repository
`error`	An error occurred while evaluating the PR

Empty Results

When no grouped source branches match the filters:

Text output: Displays No grouped source branches found.
JSON output: Returns {"groups": []}
Exit code: 0 — empty results are not an error

This can happen when:

No open PRs exist in the organization
All PRs have unique source branch names and --min-group-size filters them out
The --source-branch-prefix filter does not match any branch names
The --repo filter limits discovery to repositories with no matching PRs

Examples

Basic report

Scan the organization and show all grouped PRs:

ghprmerge report --org myorg

Filter by author

Show only PRs opened by dependabot[bot]:

ghprmerge report --author 'dependabot[bot]' --org myorg

Show only PRs opened by a specific user:

ghprmerge report --author JaredHatfield --org myorg

Filter by branch prefix

Show only Dependabot Go module updates:

ghprmerge report --org myorg --source-branch-prefix dependabot/go_modules/

Filter by multiple prefixes

Show Dependabot updates for both Go and npm:

ghprmerge report --org myorg --source-branch-prefix dependabot/go_modules/,dependabot/npm_and_yarn/

Include single-PR groups

Lower the minimum group size to include branches with only one PR:

ghprmerge report --org myorg --min-group-size 1

Brief output

Show only branch names and counts:

ghprmerge report --org myorg --verbosity brief

Verbose output

Show branch names, counts, statuses, and PR titles:

ghprmerge report --org myorg --verbosity verbose

Limit to specific repos

Report on specific repositories only:

ghprmerge report --org myorg --repo repo-a --repo repo-b

JSON output for scripting

Get structured output for automation pipelines:

ghprmerge report --json --org myorg | jq '.groups[] | select(.count >= 5)'

Combine with repo limit

Scan at most 20 repositories:

ghprmerge report --repo-limit 20 --org myorg

Disable colored output

Useful for CI environments or piping to a file:

ghprmerge report --no-color --org myorg

Identify PRs ready to merge

Use JSON output to find groups where all PRs are passing:

ghprmerge report --json --org myorg | jq '
  .groups[] | select(
    all(.pullRequests[]; .status == "passing")
  )
'

Feed report into merge

Use the report to identify a branch, then merge it:

# Step 1: Find grouped branches
ghprmerge report --org myorg --verbosity brief

# Step 2: Merge a specific branch from the report
ghprmerge merge --org myorg --source-branch dependabot/go_modules/foo-1.2.3