How do I watch until completion?

Use --watch; you can add --fail-fast to exit on the first failure while watching.

How do I get a machine-readable output?

Add --json with fields like name, state, and bucket; you can pipe to --jq for filtering.

What does the bucket field mean?

The bucket JSON field categorizes state into pass, fail, pending, skipping, or cancel.

gh-pr-checks

npx machina-cli add skill dceoy/github-cli-agent-skills/gh-pr-checks --openclaw

Files (1)

SKILL.md

2.3 KB

GitHub PR Checks

When to use

The user asks about CI status or checks on a PR.
Monitoring build/test results before merge.
Waiting for checks to complete.

Inputs to confirm

PR number, URL, or branch name (or current branch PR).
Whether to watch/wait for completion.
Target repo if not current (--repo OWNER/REPO).

Workflow

Verify auth:
```
gh --version
gh auth status
```

View check status:

gh pr checks 123
gh pr checks  # current branch PR

Watch checks until completion:

gh pr checks 123 --watch
gh pr checks 123 --watch --fail-fast

Get JSON output for scripting:

gh pr checks 123 --json name,state,conclusion

View only required checks:
```
gh pr checks 123 --required
```

Examples

# Check current PR status
gh pr checks

# Watch until all checks complete
gh pr checks 123 --watch

# Exit on first failure while watching
gh pr checks 123 --watch --fail-fast

# View in browser
gh pr checks 123 --web

# Get JSON with bucket categorization
gh pr checks 123 --json name,state,bucket --jq '.[] | select(.bucket == "fail")'

Flags reference

Flag	Description
`--watch`	Watch checks until they finish
`--fail-fast`	Exit watch on first failure
`-i, --interval`	Refresh interval in seconds (default 10)
`--required`	Show only required checks
`--json`	Output JSON (fields: bucket, name, state, etc.)
`-w, --web`	Open checks in browser

Exit codes

0: All checks passed
1: Error occurred
8: Checks still pending

Notes

The bucket JSON field categorizes state into: pass, fail, pending, skipping, cancel.
Use --required to focus on blocking checks.
--watch is useful in CI scripts waiting for dependent checks.

References

GitHub CLI manual: https://cli.github.com/manual/
gh pr checks --help

Source

git clone https://github.com/dceoy/github-cli-agent-skills/blob/main/skills/gh-pr-checks/SKILL.mdView on GitHub

Overview

gh pr checks lets you view CI/CD check status for a GitHub pull request using the gh CLI. It helps you monitor build and test results to decide when a PR is ready to merge. You can target a specific PR by number, URL, or branch and export JSON for automation.

How This Skill Works

The GitHub CLI queries the PR checks and returns their status. You can fetch a specific PR with gh pr checks <PR> or inspect the current branch PR with gh pr checks. For automation, use --json to output structured data, and --watch to monitor checks until completion.

When to Use It

You need visibility into CI status or checks on a PR
You want to monitor build/test results before merging
You need to wait for checks to complete before taking action
You require a machine-readable JSON output for scripting
You want to focus on blocking checks with --required

Quick Start

Step 1: gh --version; gh auth status
Step 2: gh pr checks <PR> (or gh pr checks for current branch)
Step 3: gh pr checks <PR> --watch (or gh pr checks <PR> --json name,state,bucket for scripting)

Best Practices

Verify authentication and CLI readiness with gh --version and gh auth status before using gh pr checks
Use --watch for long-running CI and tests to avoid manual polling
Output JSON with --json to enable scripting and automation
Filter to blocking checks with --required to prioritize gating failures
When exploring visually, use --web to open checks in a browser

Example Use Cases

Check current PR status: gh pr checks
Watch until all checks complete for PR 123: gh pr checks 123 --watch
Exit on first failure while watching: gh pr checks 123 --watch --fail-fast
View checks in browser: gh pr checks 123 --web
Get JSON with bucket categorization for automation: gh pr checks 123 --json name,state,bucket

Frequently Asked Questions

Add this skill to your agents