Read GitHub Pull Request Checks with gh pr checks

gh pr checks tells you in one line whether a pull request is passing, still running or on fire. The examples use GitHub CLI gh 2.87.3, installed from package gh on this machine, and the gh pr checks subcommand.

Allow about ten minutes. You need gh, a GitHub login with access to the repository, and a shell. These commands only read pull request status, except --web, which opens a browser. No elevated privileges are needed.

1. Confirm the command and login

Check the installed version and authentication before investigating a pull request:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth status

The second command should report an active account for the host you use. If it reports that authentication is required, stop here and authenticate with your normal gh auth login procedure. Do not paste an access token into a shell command or a support ticket.

Checkpoint: gh pr checks --help should show the command synopsis and the JSON fields bucket, completedAt, description, event, link, name, startedAt, state and workflow.

2. Show checks for the current branch

From a local checkout, run:

$ gh pr checks

With no argument, gh selects the pull request belonging to the current branch. Convenient, but it is also an easy distraction trap: verify the branch with git branch --show-current before trusting the result.

For a different pull request, pass its number, URL or branch name:

$ gh pr checks 123
$ gh pr checks https://github.com/OWNER/REPOSITORY/pull/123
$ gh pr checks feature/example-change

Replace OWNER, REPOSITORY and the example number or branch with real values. If the checkout is not the repository you mean to query, select it explicitly with the inherited -R option:

$ gh pr checks 123 -R OWNER/REPOSITORY

A good result is a check list for one pull request. An error about a missing pull request, repository or permission is a selection or access problem, not evidence that CI has failed.

3. Narrow the result to required checks

Branch protection often makes required checks the useful first view. Add --required:

$ gh pr checks 123 --required -R OWNER/REPOSITORY

This filters the displayed checks. It does not rerun jobs, change branch protection, or declare an optional check safe to ignore. Keep the unfiltered command handy for when a failure might sit in an optional job, or when you need the complete audit trail. A green required-check view is not the same thing as your organisation's merge decision: review approvals, merge queue rules and any checks this command does not show, separately.

4. Wait for pending checks

Use watch mode when the pull request is still running:

$ gh pr checks 123 --watch -R OWNER/REPOSITORY

The command refreshes every ten seconds by default and keeps going until the checks finish. Use --interval for a different cadence:

$ gh pr checks 123 --watch --interval 30 -R OWNER/REPOSITORY

Watch mode is not a background service. Pressing Ctrl-C stops your local wait; it does not cancel the GitHub jobs or change their result. Add --fail-fast to exit watch mode the moment a check fails:

$ gh pr checks 123 --watch --fail-fast -R OWNER/REPOSITORY

Checkpoint: a script or CI wrapper must handle the documented additional exit status 8, which means checks are pending. The general exit statuses still apply: 0 is successful execution, 1 is an error, 2 is cancellation, and 4 requires authentication.

5. Produce stable JSON for a script

Human-readable columns suit a terminal; scripts should ask for named fields instead. This example requests a compact set and uses --jq to print one line per check:

$ gh pr checks 123 \
    --json name,state,bucket,link \
    --jq '.[] | [.name, .state, .bucket, .link] | @tsv' \
    -R OWNER/REPOSITORY

The output is tab-separated data. A bucket groups the check state into pass, fail, pending, skipping or cancel. Keep the raw JSON when another program needs to make a decision, and do not parse terminal spacing or colours.

For a report meant for people, use a Go template instead:

$ gh pr checks 123 \
    --json name,state,bucket \
    --template '{{range .}}{{printf "%s: %s (%s)\n" .name .state .bucket}}{{end}}' \
    -R OWNER/REPOSITORY

These formatters only see fields returned by --json. If a field is missing from that list, add it explicitly. gh pr checks --help lists the available names; do not assume a field from another gh command exists here too.

6. Diagnose the common failure modes

• No-argument form selects nothing. You are probably not on a branch associated with a pull request. Check the branch, then pass the pull request number or URL explicitly, or use -R OWNER/REPOSITORY for another repository.
• Authentication fails. Run gh auth status and repair the login with your approved account and host. A successful login still needs permission to read the repository and its checks. Do not work around a permission error by sharing someone else's credentials.
• Command exits with status 8. That is not a failed build; treat it as pending, either wait with --watch or report the pending state to the caller. A failing, cancelled and skipped check are separate JSON states, so keep those distinctions in automation.

If you only need to inspect details in GitHub's web interface, --web opens the checks page for the pull request:

$ gh pr checks 123 --web -R OWNER/REPOSITORY

This launches your configured browser and is unsuitable for a headless script. There is nothing to undo: close the tab when finished, and use the terminal forms for repeatable checks.

Done means

• Login confirmed. gh auth status reports the intended active account and host.
• Target selected. You picked the intended pull request by number, URL, branch or verified current branch.
• Scope decided. You know whether you need all checks or only checks marked required.
• Pending handled. Watch mode or exit status 8 is dealt with when CI is still running.
• Automation is stable. Scripts use JSON fields rather than scraping human-readable columns.