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:

   code

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

2. •

   Play audio announcement:

   bash

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

On Failure

1. •

   Print failure summary with details:

   code

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

2. •

   Get detailed failure information if available:

   bash

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

3. •

   Print links to failed check details

4. •

   Play audio announcement:

   bash

   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