GitHub PR Checks Skill

Overview

This skill enables agents to monitor, interpret, and wait for GitHub Pull Request check statuses. Use this skill when you need to:

• •Verify all CI/CD checks are passing before merging
• •Wait for pending checks to complete
• •Understand why a check failed
• •Determine if a PR is ready for merge based on required checks
• •Poll for check completion with intelligent backoff

Output

Instructions

Follow these steps to monitor and manage GitHub PR checks:

1. •

   Determine Your Objective

   • •Review the decision tree below to identify which script matches your needs
   • •Consider whether you need real-time polling or just current status
   • •Identify if you need all checks or only required checks
2. •

   Select and Execute the Appropriate Script

   • •Use eia_get_pr_checks.py for current status snapshots
   • •Use eia_wait_for_checks.py for polling until completion
   • •Use eia_get_check_details.py for investigating specific failures
   • •Refer to the Scripts Reference section for command-line options
3. •

   Parse the JSON Output

   • •All scripts return structured JSON to stdout
   • •Check the all_passing or final_status field for overall status
   • •Examine individual check objects for detailed information
   • •Use the exit code for automated decision-making
4. •

   Interpret Check Conclusions

   • •Refer to the Check Status Quick Reference table
   • •Identify which checks are required vs optional
   • •Determine if action is needed (see Action Required column)
5. •

   Take Appropriate Action

   • •If all passing: proceed with merge or next workflow step
   • •If failing: investigate using eia_get_check_details.py
   • •If pending: wait using eia_wait_for_checks.py with appropriate timeout
   • •If timeout: check CI runner status and consider increasing timeout
6. •

   Handle Errors Gracefully

   • •Check exit codes (see Exit Codes section)
   • •Refer to Error Handling section for common issues
   • •Use debugging commands to verify authentication and access

Checklist

Copy this checklist and track your progress:

• • Verify gh CLI is authenticated: gh auth status
• • Determine objective (current status, wait for completion, investigate failure)
• • Get current PR check status: python eia_get_pr_checks.py --pr <number>
• • Review all_passing field in JSON output
• • If checks pending, wait for completion: python eia_wait_for_checks.py --pr <number> --timeout <seconds>
• • If checks failing, investigate: python eia_get_check_details.py --pr <number> --check "<name>"
• • Interpret check conclusions using Quick Reference table
• • Identify required vs optional failing checks
• • Take appropriate action based on results:
  • • If all passing: proceed with merge
  • • If failing: fix issues and push new commit
  • • If timeout: check CI runner status
• • Handle any errors using exit codes (0=success, 1-4=errors)
• • Verify PR is ready for merge before proceeding

When to Use This Skill

Decision Tree: Which Script Do I Need?

START: What do you need to know about PR checks?
│
├─► "What is the current status of all checks?"
│   └─► Use: eia_get_pr_checks.py --pr <number>
│       Returns: List of all checks with their conclusions
│
├─► "Are all required checks passing?"
│   └─► Use: eia_get_pr_checks.py --pr <number> --required-only
│       Returns: Status of only required checks
│
├─► "I need to wait until checks complete"
│   └─► Use: eia_wait_for_checks.py --pr <number> --timeout <seconds>
│       Returns: Final status after all checks complete or timeout
│
├─► "Why did a specific check fail?"
│   └─► Use: eia_get_check_details.py --pr <number> --check <name>
│       Returns: Detailed check info including logs URL
│
└─► "Is this PR ready to merge?"
    └─► Use: eia_get_pr_checks.py --pr <number> --summary-only
        Returns: Simple pass/fail summary

Check Status Quick Reference

Scripts Reference

1. eia_get_pr_checks.py

Purpose: Retrieve all check statuses for a Pull Request.

Usage:

# Get all checks for PR #123
python eia_get_pr_checks.py --pr 123

# Get only required checks
python eia_get_pr_checks.py --pr 123 --required-only

# Get summary only (pass/fail count)
python eia_get_pr_checks.py --pr 123 --summary-only

# Specify repository (if not in git directory)
python eia_get_pr_checks.py --pr 123 --repo owner/repo

Output Format:

{
  "pr_number": 123,
  "total_checks": 5,
  "passing": 3,
  "failing": 1,
  "pending": 1,
  "skipped": 0,
  "all_passing": false,
  "required_passing": false,
  "checks": [
    {
      "name": "build",
      "status": "completed",
      "conclusion": "success",
      "required": true
    }
  ]
}

2. eia_wait_for_checks.py

Purpose: Poll and wait for all PR checks to complete.

Usage:

# Wait up to 10 minutes for checks
python eia_wait_for_checks.py --pr 123 --timeout 600

# Wait only for required checks
python eia_wait_for_checks.py --pr 123 --required-only --timeout 300

# Custom polling interval (default 30s)
python eia_wait_for_checks.py --pr 123 --interval 60

Output Format:

{
  "pr_number": 123,
  "completed": true,
  "timed_out": false,
  "final_status": "all_passing",
  "wait_time_seconds": 180,
  "checks_summary": {
    "passing": 5,
    "failing": 0,
    "pending": 0
  }
}

3. eia_get_check_details.py

Purpose: Get detailed information about a specific check.

Usage:

# Get details for a specific check
python eia_get_check_details.py --pr 123 --check "build"

# Include logs URL
python eia_get_check_details.py --pr 123 --check "test" --include-logs-url

Output Format:

{
  "name": "build",
  "status": "completed",
  "conclusion": "failure",
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:05:30Z",
  "duration_seconds": 330,
  "details_url": "https://github.com/...",
  "logs_url": "https://github.com/.../logs",
  "output": {
    "title": "Build failed",
    "summary": "Compilation error in src/main.py"
  }
}

Reference Documents

Understanding CI Status Interpretation

For detailed guidance on interpreting check statuses, see ci-status-interpretation.md:

• •
  1. •Understanding GitHub Check Conclusions
  • •1.1 Complete list of conclusion values
  • •1.2 When each conclusion occurs
  • •1.3 How to respond to each conclusion
• •
  1. •Required vs Optional Checks
  • •2.1 How branch protection defines required checks
  • •2.2 Identifying required checks programmatically
  • •2.3 Handling optional check failures
• •
  1. •Check Run vs Check Suite
  • •3.1 Difference between check runs and check suites
  • •3.2 When to query which API endpoint
  • •3.3 Aggregating results from multiple providers
• •
  1. •Common CI Providers
  • •4.1 GitHub Actions check naming conventions
  • •4.2 CircleCI integration patterns
  • •4.3 Jenkins GitHub plugin behavior
  • •4.4 Third-party status checks

Polling Strategies

For guidance on waiting for checks, see polling-strategies.md:

• •
  1. •When to Poll for Check Completion
  • •1.1 Scenarios requiring polling
  • •1.2 Avoiding unnecessary polling
  • •1.3 Webhook alternatives
• •
  1. •Exponential Backoff Implementation
  • •2.1 Why exponential backoff matters
  • •2.2 Recommended backoff parameters
  • •2.3 Jitter for distributed systems
• •
  1. •Timeout Handling
  • •3.1 Setting appropriate timeouts
  • •3.2 Graceful timeout behavior
  • •3.3 Partial completion scenarios
• •
  1. •Partial Success Scenarios
  • •4.1 Handling mixed results
  • •4.2 Re-running failed checks
  • •4.3 Determining merge readiness with failures

Examples

Example 1: Check PR Status Before Merge

# Get all check statuses for PR #123
python eia_get_pr_checks.py --pr 123

# If all_passing is true, proceed with merge
# If not, investigate failing checks

Example 2: Wait for CI to Complete

# Wait up to 10 minutes for all checks to complete
python eia_wait_for_checks.py --pr 456 --timeout 600

# If timed_out is true, check CI runner status
# If completed is true and final_status is all_passing, merge is safe

Error Handling

Common Issues

Debugging Commands

# Verify gh CLI authentication
gh auth status

# Check repository access
gh repo view owner/repo

# Manual check inspection
gh pr checks <number> --json name,status,conclusion

# View raw API response
gh api repos/owner/repo/commits/SHA/check-runs

Prerequisites

• •gh CLI: Must be installed and authenticated (gh auth login)
• •Repository access: Read access to the target repository
• •Python 3.8+: For running the scripts

Exit Codes (Standardized)

All scripts use standardized exit codes for consistent error handling:

Note: eia_wait_for_checks.py returns exit code 3 on timeout. Check the JSON output's timed_out field for details.

Resources

• •references/ci-status-interpretation.md - Understanding check conclusions and required checks
• •references/polling-strategies.md - When and how to poll for check completion