# gh search prs: Find Pull Requests in CI

> gh search prs finds pull requests across repos by author, label, state, and more. Reference for --state, --label, --json, and the auth errors in CI.

Source: https://latchkey.dev/learn/command-reference/gh-search-prs  
Updated: 2026-06-30

gh search prs searches pull requests across GitHub with qualifiers like author, label, and state.

Reporting and reminder bots use gh search prs to list every open PR matching a policy across an organization.

## What it does

gh search prs queries GitHub for pull requests matching a search term and qualifiers such as --author, --label, --state, and --review. --json returns fields like number, title, and url for downstream processing.

## Common usage

```Terminal
gh search prs --owner my-org --state open --label "needs-review"
gh search prs "flaky test" --author app/dependabot
gh search prs --review-requested @me --json number,title,url
```

## Flags

| Flag | What it does |
| --- | --- |
| --state <open|closed> | Filter by pull request state |
| --label <name> | Filter by label |
| --author <user> | Filter by author |
| --review-requested <user> | PRs requesting a review from a user (@me supported) |
| -L, --limit <n> | Maximum results to return |
| --json <fields> | Output selected fields as JSON |

## In CI

Set GH_TOKEN. Search needs authentication; the default GITHUB_TOKEN searches only repos it can read. @me resolves to the token identity, which is github-actions[bot] in Actions, so use an explicit --author or --owner when running as a bot.

## Common errors in CI

"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. "HTTP 403: API rate limit exceeded" means too many queries; slow down. An empty result is common when @me resolves to the bot rather than a human author.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### gh search prs: Find Pull Requests in CI?

Reporting and reminder bots use gh search prs to list every open PR matching a policy across an organization.

### What it does?

gh search prs queries GitHub for pull requests matching a search term and qualifiers such as --author, --label, --state, and --review. --json returns fields like number, title, and url for downstream processing.

### In CI?

Set GH_TOKEN. Search needs authentication; the default GITHUB_TOKEN searches only repos it can read. @me resolves to the token identity, which is github-actions[bot] in Actions, so use an explicit --author or --owner when running as a bot.

### Common errors in CI?

"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. "HTTP 403: API rate limit exceeded" means too many queries; slow down. An empty result is common when @me resolves to the bot rather than a human author.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt