aaddrick/gh-cli-search/gh-search-issues

GitHub CLI: Search Issues

Overview

Search for issues across GitHub repositories using gh search issues. Add --include-prs flag to also search pull requests.

⚠️ CRITICAL: Search vs List Commands

`gh search issues` - 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 issues in the microsoft organization", "Search for bugs in kubernetes repos"

`gh issue list` - Current repository only (NOT THIS SKILL):

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

When user says "my issues" or "issues here" → Use `gh issue list` (NOT this skill) When user specifies repo/org or cross-repo search → Use `gh search issues` (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 my open issues across GitHub")
• Complex queries needing search qualifiers (e.g., "comments>50 across microsoft repos")

DO NOT use this skill when:

• User asks about "issues in this repo" or "my issues here"
• No repo/org is specified and context is clearly current repository
• Use gh issue list for current repo operations instead

Syntax

gh search issues [<query>] [flags]

Key Flags Reference

User Filters

Issue Attributes

Repository Filters

Engagement Metrics

Date Filters

Search Scope

Output & Sorting

JSON Output Fields

assignees, author, authorAssociation, body, closedAt, commentsCount, createdAt, id, 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 issues -- "search-terms -qualifier:value" ❌ Wrong: gh search issues "search-terms" --flag=-value ❌ Wrong: gh search issues "search-terms" --flag=!value ❌ Wrong: gh search issues --label!=bug

Examples:

• gh search issues -- "bug -label:wontfix" (exclude label)
• gh search issues -- "crash -assignee:olduser" (exclude assignee)
• gh search issues -- "error -author:bot" (exclude author)
• gh search issues -- "performance -milestone:v1.0" (exclude milestone)

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 issues "bug" --label urgent --state open

Query Syntax with `--` (required for exclusions):

gh search issues -- "bug -label:duplicate -label:wontfix"

⚠️ 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 issues -- "bug -label:duplicate"
 
# Exclude specific assignee
gh search issues -- "crash -assignee:olduser"

Multiple exclusions:

# Exclude multiple labels
gh search issues -- "bug -label:duplicate -label:wontfix"
 
# Exclude author and label
gh search issues -- "performance -author:bot -label:invalid"

Combine with positive filters using flags:

# Wrong - mixing syntaxes:
gh search issues "bug" --state open -label:duplicate  # ❌
 
# Correct - use query syntax for everything when excluding:
gh search issues -- "bug state:open -label:duplicate"  # ✅

PowerShell exclusions:

# Use --% to prevent PowerShell parsing
gh --% search issues -- "bug -label:duplicate"

Common Exclusion Patterns:

2. Special Values

• @me - Current authenticated user

``bash gh search issues --assignee @me --state open ``

3. Quoting Rules

Multi-word search:

gh search issues "memory leak"

Labels with spaces:

gh search issues -- 'crash label:"bug fix"'

Comparison operators need quotes:

gh search issues "performance" --comments ">10"

Common Use Cases

Find your open issues across all of GitHub:

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

Find unassigned bugs in a specific org:

gh search issues --label bug --no-assignee --state open --owner kubernetes

Find highly discussed issues in a specific repo:

gh search issues --comments ">50" --state open --repo microsoft/vscode

Find stale issues across multiple repos:

gh search issues --state open --updated "<2023-01-01" --owner myorg

Search issues AND PRs in an organization:

gh search issues "authentication" --include-prs --state open --owner github

Exclude specific labels in cross-repo search:

gh search issues -- "crash -label:duplicate -label:wontfix" --repo cli/cli

Find issues in milestone across repos:

gh search issues --milestone v2.0 --state open --owner golang

Find issues by title only in specific language repos:

gh search issues "error in:title" --state open --language rust

Common Mistakes

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 issues "crash 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-prs, gh-search-repos