gh-pr-checks

Show checks for the pull request of the current branch

$ gh pr checks

$ gh pr checks [pr_number]

$ gh pr checks [pr_number] --watch

$ gh pr checks [pr_number] --required

gh pr checks [<number> | <url> | <branch>] [flags]

--check <name>
    Show detailed info for a specific check run name

--interval <duration>
    Refresh interval when watching checks (default: 5s)

--json
    Print output in JSON format instead of the default table

--limit <int>
    Maximum number of checks to list (default: 20)

--repo <repo>
    Select another repository using [HOST/]OWNER/REPO format

--status <status>
    Filter by status: pending, skipped, passing, failing, cancelled

--watch
    Watch check runs until they complete

--web
    Open check runs page in default browser

The gh pr checks command is part of the GitHub CLI toolset, designed to display the status of check runs associated with a specific pull request (PR) on GitHub. Check runs typically come from GitHub Actions workflows, third-party CI/CD services, or custom status checks required for PR approval.

It provides a concise summary of pending, passing, failing, skipped, or cancelled checks directly in the terminal, helping developers quickly assess PR readiness without opening a web browser. When invoked on the current branch's PR or a specified one, it lists check names, statuses, and durations.

Key use cases include CI/CD pipeline monitoring during code reviews, automated testing verification, and troubleshooting build failures. Supports live watching of checks until completion and filtering by status or specific check names. Integrates seamlessly with other gh pr subcommands for streamlined GitHub workflows.

Ideal for teams using GitHub for version control, it reduces context-switching and accelerates merge decisions. Output can be formatted as JSON for scripting or piped into other tools. Requires authentication via gh auth login.

Requires GitHub CLI installed and authenticated. Only shows checks visible to the authenticated user. Does not re-run checks; use gh run rerun for that. Web output opens GitHub UI, not always terminal-preferred.

gh pr checks
gh pr checks --watch
gh pr checks 123 --status failing --repo owner/repo

0: success
1: error (e.g., no PR found, auth failure)

Introduced in GitHub CLI v1.0.0 (Dec 2020) with core PR commands. Enhanced in v2.0+ with --watch and JSON support for better automation. Evolved alongside GitHub Actions growth post-2019.

gh-pr-status(1), gh-pr-view(1), gh-run-list(1), gh-workflow-list(1)