gh pr checks: Read PR Status Checks in CI
gh pr checks lists every status check on a pull request and reports pass, fail, or pending.
When a pipeline needs to gate on another PR finishing its checks, gh pr checks gives a clean exit code and an optional blocking wait.
What it does
gh pr checks prints the state of each check run and status context attached to a pull request. It exits 0 when all checks pass, 8 when checks are still pending, and 1 when any check fails, so you can gate a job on the result.
Common usage
gh pr checks 123
gh pr checks 123 --watch
gh pr checks --required
gh pr checks 123 --json name,state,conclusionFlags
| Flag | What it does |
|---|---|
| --watch | Block and refresh until all checks complete |
| --required | Only show checks required by branch protection |
| --fail-fast | With --watch, exit as soon as one check fails |
| --interval <n> | Refresh interval in seconds when watching |
| --json <fields> | Output selected fields as JSON |
| -R, --repo <owner/repo> | Target a specific repository |
In CI
Set GH_TOKEN: ${{ github.token }} (or a PAT with repo scope) so gh authenticates, and add permissions: { checks: read, pull-requests: read } to the job. Run gh pr checks --required --watch to block a downstream job until required checks land.
Common errors in CI
"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN was not exported. "no checks reported on the 'main' branch" means no check runs exist yet, not a failure. A non-zero exit of 8 is the pending state, so test the exit code rather than assuming 0 vs 1.