# gh pr checks: Read PR Status Checks in CI

> gh pr checks shows the status of CI checks on a pull request and can block until they finish. Reference for --watch, --required, --json, and CI auth errors.

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

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

```Terminal
gh pr checks 123
gh pr checks 123 --watch
gh pr checks --required
gh pr checks 123 --json name,state,conclusion
```

## Flags

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

```.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 pr checks: Read PR Status Checks in CI?

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.

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

---

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