GitHub PR Checks Skill
Overview
Monitor, interpret, and wait for GitHub PR check statuses. Use when verifying CI/CD checks before merge, waiting for pending checks, or investigating failures.
Prerequisites
- gh CLI installed and authenticated (
gh auth login) - Repository access: read access to target repository
- Python 3.8+ for running scripts
Instructions
- Get current status:
python amia_get_pr_checks.py --pr <number> - Check required only: add
--required-onlyflag - Quick mergeable check: add
--summary-onlyflag - Wait for completion:
python amia_wait_for_checks.py --pr <number> --timeout <seconds> - Investigate failure:
python amia_get_check_details.py --pr <number> --check "<name>" - Parse JSON output: check
all_passingorfinal_statusfield - Act on results: merge if passing, fix if failing, wait if pending
Checklist
Copy this checklist and track your progress:
- Verify gh CLI authenticated:
gh auth status - Get PR check status with
amia_get_pr_checks.py - Review
all_passingfield in JSON output - If pending, wait with
amia_wait_for_checks.py - If failing, investigate with
amia_get_check_details.py - Identify required vs optional failing checks
- Take action: merge / fix / wait
- Verify PR is ready for merge before proceeding
Output
| Output Type | Format | Contents |
|---|---|---|
| Check Status Report | JSON | Pass/fail counts, individual conclusions, required check status |
| Wait Completion Report | JSON | Final status, timeout status, wait time, checks summary |
| Check Details | JSON | Duration, logs URL, failure output for a specific check |
| Exit Code | Integer | 0=success, 1=bad params, 2=not found, 3=API error, 4=not auth |
Output discipline: All scripts support
--output-file <path>. Use it in automated workflows to minimize token consumption.
Error Handling
Exit 1: bad params. Exit 2-4: API errors. See detailed guide in Resources.
Resources
Full reference: detailed-guide:
- Decision Tree: Which Script Do I Need?
- Check Status Quick Reference
- Scripts Reference
- amia_get_pr_checks.py
- amia_wait_for_checks.py
- amia_get_check_details.py
- Error Handling
- Common Issues
- Exit Codes (Standardized)
- Debugging Commands
Examples
Example 1: Check and Wait for PR Merge Readiness
# Get current status
python amia_get_pr_checks.py --pr 123
# If checks pending, wait up to 10 minutes
python amia_wait_for_checks.py --pr 456 --timeout 600
# If a check failed, get details
python amia_get_check_details.py --pr 456 --check "build"