GitHub CI Monitor

Monitor GitHub Pull Request CI/CD checks continuously until all checks complete, then provide visual and audio notification of the result.

Core Behavior

CRITICAL: Be tenacious. CI pipelines vary wildly in duration—some complete in 2 minutes, others take over an hour. Never give up monitoring. Continue polling until receiving a definitive pass or fail result, or until explicitly stopped by the user.

Prerequisites

Ensure the GitHub CLI (gh) is installed and authenticated. Verify with:

gh auth status

Monitoring Workflow

Step 1: Identify the PR

Determine the PR to monitor. If user specifies a PR number, use that. Otherwise, detect from current branch:

gh pr view --json number,title,url,headRepository

If no PR exists for the current branch, inform the user and offer to help create one.

Step 2: Start Monitoring Loop

Begin the polling loop with clear user feedback:

1. Print initial status message: "Monitoring PR #X: [title]"
2. Print the PR URL for reference
3. Begin polling every 60 seconds

Step 3: Poll for Check Status

Use gh pr checks to get current status:

gh pr checks <PR_NUMBER> --json name,state,conclusion

Check states:

• PENDING or QUEUED - Still running, continue polling
• IN_PROGRESS - Still running, continue polling
• COMPLETED - Check finished, examine conclusion

Check conclusions (when completed):

• SUCCESS - Check passed
• FAILURE - Check failed
• CANCELLED - Check was cancelled (treat as failure)
• SKIPPED - Check was skipped (treat as success)
• NEUTRAL - Neutral result (treat as success)

Step 4: Determine Overall Status

All checks must complete before announcing results:

• All checks completed with SUCCESS/SKIPPED/NEUTRAL: CI passed
• Any check with FAILURE/CANCELLED: CI failed
• Any check still PENDING/QUEUED/IN_PROGRESS: Continue polling

Step 5: Handle Completion

When all checks complete:

On Success

1. Print success summary:

   ✅ CI PASSED - PR #X: [title]
   All checks completed successfully.
   URL: [pr_url]

2. Play audio announcement:

   say "GitHub [repo-name] PR [pr-number] completed CI successfully" 2>/dev/null

On Failure

1. Print failure summary with details:

   ❌ CI FAILED - PR #X: [title]
   
   Failed checks:
   - [check_name]: [conclusion]
   - [check_name]: [conclusion]
   
   URL: [pr_url]

2. Get detailed failure information if available:

   gh pr checks <PR_NUMBER> --json name,state,conclusion,detailsUrl

3. Print links to failed check details

4. Play audio announcement:

   say "GitHub [repo-name] PR [pr-number] completed CI unsuccessfully" 2>/dev/null

Audio Notification

Use macOS say command directly with stderr suppressed:

say "GitHub [repo-name] PR [pr-number] completed CI successfully" 2>/dev/null
say "GitHub [repo-name] PR [pr-number] completed CI unsuccessfully" 2>/dev/null

The 2>/dev/null silently ignores errors on systems without say.

Use the repository name from gh pr view --json headRepository, extracting just the repo name (not owner/repo).

Polling Behavior

Interval

Poll every 60 seconds. Between polls, simply wait—do not output status unless there are changes.

Progress Updates

Provide periodic updates to show monitoring is active:

• Every 5 minutes: Print brief status "Still monitoring... X checks pending"
• On state changes: Print when individual checks complete

Error Handling

Network or API errors should not terminate monitoring:

• On transient error: Wait 60 seconds and retry
• After 3 consecutive errors: Inform user but continue trying
• Never give up unless user explicitly stops

User Interruption

The user can stop monitoring at any time by:

• Saying "stop monitoring" or similar
• Starting a new task
• Pressing Ctrl+C

Example Session

User: monitor the PR

Claude: Monitoring PR #42: Add user authentication feature
URL: https://github.com/acme/webapp/pull/42

Checking CI status...
- build: ⏳ in progress
- test: ⏳ pending
- lint: ✅ success

[60 seconds later]

- build: ✅ success
- test: ⏳ in progress
- lint: ✅ success

[60 seconds later]

- build: ✅ success
- test: ✅ success
- lint: ✅ success

✅ CI PASSED - PR #42: Add user authentication feature
All checks completed successfully.
URL: https://github.com/acme/webapp/pull/42

[Audio: "GitHub webapp PR 42 completed CI successfully"]

Proactive Monitoring

When working on a PR (creating it, pushing updates, or responding to review), proactively offer to monitor CI if the user would benefit. For example, after running gh pr create, offer: "Would you like me to monitor the CI checks for this PR?"

When Claude has been doing automated work and creates or updates a PR, automatically start monitoring unless the user has indicated they don't want notifications.

Key Points

1. Never give up: Some CI pipelines take an hour or more. Keep polling.
2. Clear output: Show what's being monitored and current status
3. Audio alert: Use say on macOS, skip gracefully elsewhere
4. Failure details: On failure, provide actionable information
5. 60-second interval: Balance responsiveness with API rate limits
6. Graceful errors: Network issues don't stop monitoring