Watch CI

Watch CI

Monitor GitHub Actions CI runs for the current HEAD (or a specified SHA) until completion, then report verdict.

Trigger

• Keywords: watch CI, check CI, CI status, monitor build, build status, is CI passing, watch actions, CI result

When NOT to Use

• Pushing code to remote (use /push-ci)
• Creating pull requests (use /create-pr)
• Running local tests (use /verify or /precommit)

Workflow

Auto-detect (branch + SHA) → Find matching runs → Quick-check status → Watch or Report → Verdict

Step 1: Resolve Target

Determine which CI runs to monitor. Use arguments if provided, otherwise auto-detect.

BRANCH=${ARG_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
HEAD_SHA=${ARG_SHA:-$(git rev-parse HEAD)}
TIMEOUT=${ARG_TIMEOUT:-10}
INTERVAL=${ARG_INTERVAL:-30}

If --run-id <id> is specified, skip run discovery and monitor that specific run directly.

Step 2: Find CI Runs

Find runs matching the target SHA on the target branch:

gh run list --branch "$BRANCH" --limit 30 \
  --json databaseId,headSha,status,name,url

Note: Use --limit 30 (not 10) to avoid missing target SHA runs on busy branches. Filter results client-side by HEAD_SHA.

Filter results to those matching HEAD_SHA.

Retry logic: If no matching runs found, retry up to 3 times by re-running the gh run list command. The natural processing delay between retries provides sufficient wait time — do not use sleep N (N ≥ 2) as the first command, the harness will block it. All retry commands must start with gh or git to match allowed-tools. CI workflows may take a few seconds to trigger after push.

If still no runs found after retries:

⚠️ No CI run detected for SHA <sha>. Possible causes:
- No workflow configured for this branch
- Path-filtered workflow didn't trigger
- Check: gh run list --branch <branch>

Step 3a: Quick Status Check

Before starting a long-running watch, check if runs are already completed:

gh run view <run-id> --json status,conclusion,name,url

Step 3b: Watch Runs

For each in-progress run, monitor with gh run watch:

gh run watch <run-id> --exit-status -i "$INTERVAL"

Poll interval: $INTERVAL defaults to 30 seconds (configurable via --interval). gh's own default is 3 seconds; at that rate, Monitor streaming surfaces ~20 notifications per minute, which has been reported as noisy. 30 seconds reduces poll noise by ~90% at the cost of ≤ 27 s additional completion-detection lag, which is negligible for typical multi-minute CI runs. Pass --interval 3 to restore the old cadence when near-real-time feedback matters.

Execution mode: Monitor streaming is the default — non-blocking, reliable notifications for each status line.

Monitor mode (default) — behavior:

1. Launch gh run watch <run-id> --exit-status -i "$INTERVAL" via Monitor tool with description: "CI run <run-id> (<name>)" and timeout_ms: TIMEOUT * 60 * 1000
2. Each stdout line (status update) arrives as a streaming notification — $INTERVAL controls how often those lines fire
3. On exit (run completes or fails), parse final output for pass/fail status
4. Report verdict

Foreground mode (--blocking) — behavior:

1. Execute gh run watch <run-id> --exit-status -i "$INTERVAL" inline via Bash
2. Wait for completion (blocking) — $INTERVAL only affects how often gh polls the API, not wall-clock completion
3. Parse output for pass/fail status
4. Report verdict

Background mode (--background) — legacy fallback only: