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:

Print initial status message: "Monitoring PR #X: [title]"
Print the PR URL for reference
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

Print success summary:

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

Play audio announcement:

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

On Failure

Print failure summary with details:

❌ CI FAILED - PR #X: [title]

Failed checks:
- [check_name]: [conclusion]
- [check_name]: [conclusion]

URL: [pr_url]

Get detailed failure information if available:

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

Print links to failed check details

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

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

ci-monitor