gh search prs: Find Pull Requests in CI
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
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,urlFlags
| 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.
- 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