Waiting for PR checks

Waiting for pull request checks

Waits until every check on a pull request has finished, then exits with a status that says how they ended, so a person or an agent can start it in the background and act on the result. It follows new pushes: the checks it waits for are always those of the pull request's latest commit. When checks fail, it lists each one with its link.

./pr-wait.py https://github.com/phpbbmodders/contactadmin/pull/42
./pr-wait.py -R phpbbmodders/contactadmin 42 --timeout 30

Exit status	Meaning
0	Every check passed (success, neutral or skipped)
1	At least one check failed, was cancelled or timed out
2	Bad arguments (with no arguments it prints help)
3	The pull request was closed or merged first
4	--timeout ran out first (default 60 minutes)
5	No check appeared on the latest commit within --first-check-wait (default 3 minutes)
6	gh is not installed, or failed five times in a row (not logged in, no such pull request, no network)

It asks GitHub every --interval seconds (default 30). A result counts only once the same finished checks have been seen for --settle seconds (default 30), because GitHub can add a run a few seconds late, such as a pull request's own run after an earlier push run has already finished. Progress lines carry the time in UTC.

Every argument and option

Argument/option	Default	Meaning
pr	Required	PR number, branch or URL accepted by gh pr view.
-R, --repo OWNER/REPO	Current repository	Explicit repository, useful with a number/branch.
-t, --timeout MINUTES	60	Overall waiting limit.
-i, --interval SECONDS	30	Time between polls.
-w, --first-check-wait MINUTES	3	Wait for checks on each newly observed commit.
-s, --settle SECONDS	30	Same completed outcomes must remain unchanged this long.
-h, --help	—	Usage.

All four timing values must be greater than zero; fractional values are accepted. A new push restarts tracking and the first-check timer for that head, but does not restart the overall timeout. Each gh request has a 60-second subprocess timeout. A missing CLI fails immediately; other CLI failures stop after five consecutive failures, with a successful request clearing that failure count. Ctrl+C exits 130.

No arguments prints help and exits 2. A repository with no checks is reported with status 5 rather than being treated as passed. The tool does not merge a PR or evaluate every branch-protection requirement.

Use the exit status in automation

if pr-wait.py -R OWNER/REPO 42 --timeout 30; then
  echo 'All observed checks passed.'
else
  result=$?
  echo "Check monitoring ended with status $result" >&2
  exit "$result"
fi

Inspect status 1 failure links, status 4 timeout, status 5 missing checks, and status 6 authentication/network failures separately. Reducing --settle risks missing late-added checks. Progress is human-readable UTC text, not a JSON interface.