GitHub CLI: Search Pull Requests

Overview

Search for pull requests across GitHub repositories using gh search prs. Includes PR-specific filters like draft status, merge state, review status, and CI checks.

⚠️ CRITICAL: Search vs List Commands

gh search prs - GitHub-wide search (THIS SKILL):

• 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 - Current repository only (NOT THIS SKILL):

• 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 (NOT this skill) When user specifies repo/org or cross-repo search → Use gh search prs (THIS skill)

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

Flag	Purpose	Example
--draft	Filter draft PRs	--draft
--merged	Filter merged PRs	--merged
--merged-at <date>	Merged at date	--merged-at ">2024-01-01"
-B, --base <string>	Base branch name	--base main
-H, --head <string>	Head branch name	--head feature-auth
--review <string>	Review status	--review approved
--review-requested <user>	Review requested from	--review-requested @me
--reviewed-by <user>	Reviewed by user	--reviewed-by octocat
--checks <string>	CI check status	--checks success

User Filters

Flag	Purpose	Example
--author <string>	Created by user	--author octocat
--assignee <string>	Assigned to user	--assignee @me
--mentions <user>	Mentions specific user	--mentions octocat
--commenter <user>	Commented by user	--commenter octocat
--team-mentions <string>	Mentions team	--team-mentions myteam

PR Attributes

Flag	Purpose	Example
--label <strings>	Has specific labels	--label bug,urgent
--state <string>	PR state: open or closed	--state open
--milestone <title>	In specific milestone	--milestone v1.0
--locked	Locked conversation	--locked
--no-label	Has no labels	--no-label

Repository Filters

Flag	Purpose	Example
--owner <strings>	Repository owner	--owner github
-R, --repo <strings>	Specific repository	--repo cli/cli
--language <string>	Repository language	--language typescript
--visibility <strings>	Repo visibility	--visibility public
--archived	In archived repos	--archived

Engagement Metrics

Flag	Purpose	Example
--comments <number>	Number of comments	--comments ">5"
--reactions <number>	Reaction count	--reactions ">10"
--interactions <number>	Comments + reactions	--interactions ">15"

Date Filters

Flag	Purpose	Example
--created <date>	Creation date	--created ">2024-01-01"
--updated <date>	Last update date	--updated ">2024-06-01"
--closed <date>	Close date	--closed "<2024-12-31"

Search Scope

Flag	Purpose	Example
--match <strings>	Search in: title, body, comments	--match title

Output & Sorting

Flag	Purpose	Example
-L, --limit <int>	Max results (default: 30)	--limit 100
--sort <string>	Sort by: comments, created, reactions, etc.	--sort updated
--order <string>	Sort direction: asc or desc	--order desc
--json <fields>	JSON output	--json number,title,state,isDraft
-w, --web	Open in browser	-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 -), you MUST use the -- separator:

✅ Correct: gh search prs -- "search-terms -qualifier:value" ❌ Wrong: gh search prs "search-terms" --flag=-value ❌ Wrong: gh search prs "search-terms" --flag=!value ❌ Wrong: 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 -- separator is required: The -- tells the shell to stop parsing flags and treat everything after it as arguments. Without it, -qualifier:value inside quotes may be misinterpreted.

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 -- (required for exclusions):

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 -- separator.

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:

User Request	Command
"Find PRs but not drafts"	gh search prs -- "feature -is:draft"
"PRs excluding specific label"	gh search prs -- "bug -label:wip"
"PRs not from bot authors"	gh search prs -- "update -author:dependabot -author:renovate"
"PRs excluding failed checks"	gh search prs -- "deploy -status:failure"
"PRs not targeting main branch"	gh search prs -- "feature -base:main"
"PRs excluding review status"	gh search prs -- "fix -review:changes_requested"
"PRs not merged yet"	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

Mistake	Problem	Fix
--label="NOT wip" or --draft=-true	Flag syntax doesn't support negation	Use query: -- "-label:wip" or -- "-is:draft"
gh search prs fix -label:wip	-label interpreted as flag	Use --: -- "fix -label:wip"
"fix NOT label:wip"	NOT keyword doesn't work	Use -: -- "fix -label:wip"
Mixing syntaxes: --draft "fix -label:wip"	Can't mix flags with query qualifiers	Use query for all: -- "fix is:draft -label:wip"
--review-requested @username	Invalid @ prefix	Use @me or drop @: --review-requested username
Not quoting comparisons	Shell interprets >	Quote: --comments ">5"
label:"needs review" outside quotes	Shell parsing error	Quote query: 'label:"needs review"'
Using --merged with --state open	Contradictory filters	Merged PRs are closed; remove --state
PowerShell without --%	Breaks with exclusions	Add: gh --%

Installation Check

If gh command not found:

# 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: to search specific fields:

• 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