GitHub CLI: Search Pull Requests

Overview

Search for pull requests across GitHub repositories using

gh search prs

⚠️ CRITICAL: Search vs List Commands

gh search prs

• Searches across multiple repositories or organizations
• Searches in specific repos outside your current directory
• Uses GitHub's search query syntax with qualifiers
• Examples: "Find draft PRs in kubernetes repos", "Search for approved PRs in microsoft org"

gh pr list

• Lists PRs in your current working directory's repo
• Uses simple flag-based filtering
• Examples: "Show my PRs in this repo", "List open PRs here"

When user says "my PRs" or "PRs here" → Use

gh pr list

gh search prs

When to Use This Skill

Use this skill when the user explicitly indicates:

• Searching across multiple repositories or organizations
• Searching in a specific repo (e.g., "in kubernetes/kubernetes")
• Cross-GitHub searches (e.g., "all draft PRs across the organization")
• Complex queries needing search qualifiers (e.g., "approved PRs with >10 comments in golang repos")

DO NOT use this skill when:

• User asks about "PRs in this repo" or "my PRs here"
• No repo/org is specified and context is clearly current repository
• Use

  gh pr list

  for current repo operations instead

Syntax

gh search prs [<query>] [flags]

Key Flags Reference

PR-Specific Filters

--draft

--draft

--merged

--merged

--merged-at <date>

--merged-at ">2024-01-01"

-B, --base <string>

--base main

-H, --head <string>

--head feature-auth

--review <string>

--review approved

--review-requested <user>

--review-requested @me

--reviewed-by <user>

--reviewed-by octocat

--checks <string>

--checks success

User Filters

--author <string>

--author octocat

--assignee <string>

--assignee @me

--mentions <user>

--mentions octocat

--commenter <user>

--commenter octocat

--team-mentions <string>

--team-mentions myteam

PR Attributes

--label <strings>

--label bug,urgent

--state <string>

--state open

--milestone <title>

--milestone v1.0

--locked

--locked

--no-label

--no-label

Repository Filters

--owner <strings>

--owner github

-R, --repo <strings>

--repo cli/cli

--language <string>

--language typescript

--visibility <strings>

--visibility public

--archived

--archived

Engagement Metrics

--comments <number>

--comments ">5"

--reactions <number>

--reactions ">10"

--interactions <number>

--interactions ">15"

Date Filters

--created <date>

--created ">2024-01-01"

--updated <date>

--updated ">2024-06-01"

--closed <date>

--closed "<2024-12-31"

Search Scope

--match <strings>

--match title

Output & Sorting

-L, --limit <int>

--limit 100

--sort <string>

--sort updated

--order <string>

--order desc

--json <fields>

--json number,title,state,isDraft

-w, --web

-w

JSON Output Fields

assignees

author

authorAssociation

body

closedAt

commentsCount

createdAt

id

isDraft

isLocked

isPullRequest

labels

number

repository

state

title

updatedAt

url

Exclusion Syntax (Critical!)

When using inline query exclusions (negations with

-

--

✅ Correct:

gh search prs -- "search-terms -qualifier:value"

gh search prs "search-terms" --flag=-value

gh search prs "search-terms" --flag=!value

gh search prs --label=-WIP

Examples:

• gh search prs -- "feature -label:draft"

  (exclude label)

• gh search prs -- "fix -is:draft"

  (exclude draft PRs)

• gh search prs -- "deploy -author:bot"

  (exclude author)

• gh search prs -- "security -review:changes_requested"

  (exclude review status)

Why the

--

--

-qualifier:value

Critical Syntax Rules

When to Use Flag Syntax vs Query Syntax

Decision Tree:

Does your search include:
  - Any exclusions (NOT, minus, without, except)?  → Use Query Syntax with `--`
  - Complex boolean logic (OR, AND)?              → Use Query Syntax with `--`

Otherwise:
  - Simple positive filters only?                  → Use Flag Syntax

Flag Syntax (for positive filters):

gh search prs "refactor" --draft --state open

Query Syntax with

--

gh search prs -- "refactor -label:wip -is:draft"

⚠️ NEVER mix both syntaxes in a single command!

1. Exclusions and Negations

CRITICAL: When excluding results, you MUST use query syntax with the

--

Exclusion Syntax Rules:

1. Use the

   --

   separator before your query
2. Use

   -qualifier:value

   format (dash prefix for negation)
3. Quote the entire query string

Examples:

Single exclusion:

# Exclude specific label
gh search prs -- "refactor -label:wip"

# Exclude draft PRs
gh search prs -- "feature -is:draft"

Multiple exclusions:

# Exclude multiple labels
gh search prs -- "bug -label:wip -label:blocked"

# Exclude draft PRs and specific review status
gh search prs -- "security -is:draft -review:changes_requested"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search prs "fix" --state open -label:wip  # ❌

# Correct - use query syntax for everything when excluding:
gh search prs -- "fix state:open -label:wip"  # ✅

PowerShell exclusions:

# Use --% to prevent PowerShell parsing
gh --% search prs -- "refactor -label:wip"

Common Exclusion Patterns:

gh search prs -- "feature -is:draft"

gh search prs -- "bug -label:wip"

gh search prs -- "update -author:dependabot -author:renovate"

gh search prs -- "deploy -status:failure"

gh search prs -- "feature -base:main"

gh search prs -- "fix -review:changes_requested"

gh search prs -- "feature -is:merged"

2. Special Values

• @me

  - Current authenticated user

  gh search prs --review-requested @me --state open
  

3. Review Status Values

• none

  - No reviews

• required

  - Review required

• approved

  - Approved

• changes_requested

  - Changes requested

4. Check Status Values

• pending

  - Checks pending

• success

  - All checks passed

• failure

  - Checks failed

5. Quoting Rules

Multi-word search:

gh search prs "bug fix"

Labels with spaces:

gh search prs -- 'refactor label:"needs review"'

Comparison operators need quotes:

gh search prs "performance" --comments ">5"

Common Use Cases

Find your open PRs across all of GitHub:

gh search prs --author @me --state open

Find PRs awaiting your review in an organization:

gh search prs --review-requested @me --state open --owner kubernetes

Find draft PRs in a specific repo:

gh search prs --draft --repo microsoft/vscode

Find merged PRs in date range across an org:

gh search prs --merged --merged-at "2024-01-01..2024-12-31" --owner golang

Find PRs with failing checks in specific repos:

gh search prs --checks failure --state open --repo cli/cli

Find approved PRs not yet merged in a repo:

gh search prs --review approved --state open --repo kubernetes/kubernetes

Find PRs by base branch in an organization:

gh search prs --base main --state open --owner github

Find PRs with specific head branch pattern across repos:

gh search prs --head feature-* --state open --language go

Exclude specific labels in cross-repo search:

gh search prs -- "refactor -label:wip -label:draft" --owner myorg

Find stale PRs across multiple repos:

gh search prs --state open --updated "<2024-01-01" --owner rust-lang

Common Mistakes

--label="NOT wip"

--draft=-true

-- "-label:wip"

-- "-is:draft"

gh search prs fix -label:wip

-label

--

-- "fix -label:wip"

"fix NOT label:wip"

NOT

-

-- "fix -label:wip"

--draft "fix -label:wip"

-- "fix is:draft -label:wip"

--review-requested @username

@

@me

@

--review-requested username

>

--comments ">5"

label:"needs review"

'label:"needs review"'

--merged

--state open

--state

--%

gh --%

Installation Check

If

gh

# Check if gh is installed
which gh

# Install: https://cli.github.com/manual/installation

If not authenticated:

# Authenticate with GitHub
gh auth login

Comparison Operators

• >

  - Greater than

• >=

  - Greater than or equal

• <

  - Less than

• <=

  - Less than or equal

• ..

  - Range:

  10..50

  or

  2024-01-01..2024-12-31

Field Qualifiers

Use

in:

• in:title

  - Search in title only

• in:body

  - Search in body only

• in:comments

  - Search in comments only

Example:

gh search prs "authentication in:title" --state open

Related

• GitHub search syntax: https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests
• For searching other resources:

  gh-search-code

  ,

  gh-search-commits

  ,

  gh-search-issues

  ,

  gh-search-repos