watching-ci-runs

name	watching-ci-runs
description	Watch a CI run's jobs to completion without idling or hand-writing a poll loop. Use when a dispatched or pushed build takes minutes to finish and its per-job results decide the next step.

Watch CI Runs Without Waiting

Native builds routinely take 10-20 minutes. Blocking on them wastes that time, and hand-rolled poll loops repeatedly get the same details wrong: emitting a line per poll, staying silent on failure, or being launched twice for one run.

Arm one watcher, then keep working.

Arm the watcher

Use the harness's event-stream monitor with the bundled script, which emits one line per job as it reaches a terminal state and exits when the run completes:

scripts/watch-run.sh <run-id> [--interval SECONDS] [--repo OWNER/REPO]

Each job result arrives as its own notification, so a failure surfaces the moment that job lands rather than when the whole run finishes. Set the monitor timeout above the expected run duration; a matrix build needs far more than the default.

Keep working while it runs

The point of an event stream is that waiting costs nothing. After arming it, start the next piece of work immediately. Never sleep, poll, or re-read the output file to pass the time — a notification will arrive.

Good use of the interval: the next bead, a review of the diff just pushed, documentation the change implies, or preparing the follow-up commit. Prefer work that does not conflict with the commit under test, so a red result does not invalidate it.

One watcher per run

Before arming, check whether a watcher for that run already exists, and stop it rather than adding a second. Two watchers on one run duplicate API calls and split the results across output files, which is how a green job goes unnoticed.

If a result arrives from elsewhere before the watcher reports, that is not a reason to start another watcher.

Report every terminal state

Emit each job's actual conclusion, whatever it is. A watcher that matches only success stays silent through a failure, and silence is indistinguishable from still-running. Ask before arming: if this run failed right now, would anything be emitted?

Tolerate transient API errors rather than dying or, worse, treating an empty response as "nothing has finished" and re-announcing every job on recovery.

Act on the result

Diagnose a failure from the logs already produced before dispatching anything new; CI time is a finite paid budget. A single failed job does not justify cancelling its siblings, whose independent results are often the faster diagnosis.