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:

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