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