Watch GitHub Action runs
This package provides one command, watch_gha_runs. It displays the status
of the latest GitHub Action runs your current branch. If any of the runs are
in progress, it will refresh the display repeatedly with the latest status.
If you like, the name can be pronounced, "Watching? Ha!"
Installation
I suggest installing with pipx:
$ pipx install watchghaNow you have a command watch_gha_runs available.
For complex defaulting, you can use a git alias. For example, this provides the same defaults, but can be adapted:
[alias]
runs = "!f() { \
watch_gha_runs $@ \
\"$(git remote get-url origin)\" \
\"$(git rev-parse --abbrev-ref HEAD)\"; \
}; f"Now git runs will show a live display of the current runs on your branch.
You can authenticate against GitHub if needed using either an entry in your
.netrc file, or by setting the GITHUB_TOKEN environment variable.
Usage
$ watch_gha_runs --help Usage: watch_gha_runs [OPTIONS] [REPO] [BRANCH] Watch GitHub Action runs. Repeatedly gets the latest status and redraws the screen, until all of the jobs are complete. REPO is a local directory or GitHub URL, defaulting to ".". BRANCH is defaulted from the git repo. Options: --sha TEXT The commit SHA to use. Must be a full SHA. --poll INTEGER How many seconds between refreshes. [default: 15] --wait-for-start Wait for jobs to start --help Show this message and exit.
Display
The output shows runs and jobs. The current step of each job is shown, with a row of bullets indicating the number of steps, and which is current:
fix: recent pypy3.9 now omits lines after jumps nedbat/fix-pypy-nightly 53923268e8f9 @08:32am
⏲ queued Tests view 4397455341
3.7 on ubuntu ↻ •••••••• Run tox for 3.7
3.8 on ubuntu ↻ •••••••• Run tox for 3.8
3.9 on ubuntu ↻ •••••••• Run tox for 3.9
3.10 on ubuntu ↻ •••••••• Run tox for 3.10
3.11 on ubuntu ↻ •••••••• Run tox for 3.11
pypy-3.7 on ubuntu ↻ •••••••• Run tox for pypy-3.7
pypy-3.9 on ubuntu ↻ •••••••• Run tox for pypy-3.9
3.7 on macos ↻ •••••••• Run tox for 3.7
3.8 on macos ↻ •••••••• Run tox for 3.8
3.9 on macos ⏲ queued
3.10 on macos ↻ •••••••• Run tox for 3.10
3.11 on macos ↻ •••••••• Run tox for 3.11
pypy-3.7 on macos ⏲ queued
pypy-3.9 on macos ⏲ queued
3.7 on windows ⏲ queued
3.8 on windows ⏲ queued
3.9 on windows ⏲ queued
3.10 on windows ↻ ••••••• Check out the repo
3.11 on windows ⏲ queued
pypy-3.7 on windows ⏲ queued
↻ in_progress Quality view 4397455342
Check types ✓ success
Build docs ↻ ••••••• Tox doc
Pylint etc ↻ ••••••• Tox lint
↻ in_progress Python Nightly Tests view 4397455346
Python 3.10-dev ↻ •••◦•••• Run tox
Python 3.11-dev ↻ •••◦•••• Run tox
Python 3.12-dev ↻ •••◦•••• Run tox
Python pypy-3.7-nightly ↻ ••◦•••••• Run tox
Python pypy-3.8-nightly ↻ ••◦•••••• Run tox
Python pypy-3.9-nightly ↻ ••◦•••••• Run tox
Jobs and runs are collapsed once all of their children are successful:
fix: recent pypy3.9 now omits lines after jumps nedbat/fix-pypy-nightly 53923268e8f9 @08:32am
✓ success Tests view 4397455341
↻ in_progress Quality view 4397455342
Check types ✓ success
Build docs ↻ ••••••• Tox doc
Pylint etc ✓ success
✗ failure Python Nightly Tests view 4397455346
Python 3.10-dev ✓ success
Python 3.11-dev ✓ success
Python 3.12-dev ✓ success
Python pypy-3.7-nightly ✓ success
Python pypy-3.8-nightly ✓ success
Python pypy-3.9-nightly ✗ failure Run tox
Once all the runs are completed, the command ends, displaying the final status:
fix: recent pypy3.9 now omits lines after jumps nedbat/fix-pypy-nightly [push] 53923268e8f9 @08:32am
✓ success Tests view 4397455341
✓ success Quality view 4397455342
✗ failure Python Nightly Tests view 4397455346
Python 3.10-dev ✓ success
Python 3.11-dev ✓ success
Python 3.12-dev ✓ success
Python pypy-3.7-nightly ✓ success
Python pypy-3.8-nightly ✓ success
Python pypy-3.9-nightly ✗ failure Run tox
Changelog
2.1.1 — 2023-07-05
- Implicit .netrc authentication stopped working, but has been fixed. Thanks, Rob Weir.
2.0.0 — 2023-07-02
- The default polling interval is now 15 seconds.
- Now the GitHub repo location and branch name are defaulted from the current git repo. The repo location can be a local directory or GitHub URL. Closes issue 7.
- A new option,
--wait-for-startwill make watch_gha_runs wait until jobs are in progress. This fixes a problem with using watch_gha_runs programmatically: it can check the run status before any new runs have started, and simply report the done state of the last bunch of runs, then quit. - Fix: if a .yml workflow file couldn't be parsed, its "run" would persist in the list of runs for longer than it should. Now those unparsable runs aren't displayed at all.
- Fix: skipped runs are considered finished, and don't need their jobs shown.
- Error reporting is improved, removing unneeded noisy tracebacks in some cases, and providing more information for GitHub API errors. Closes issue 8.
- More operations are retried on failure, fixing issue 10.
- Interrupting with ctrl-C will set the exit status to 2.
1.0.0 — 2023-04-15
- The
--polloption sets the number of seconds to wait between refreshes. - Requests to GitHub are now made asynchronously, speeding execution.
- Redirections from GitHub (for example, if a repo is renamed or moved) are followed transparently.
- The exit code is now 1 if any runs failed, 0 if all were successful.
- Long lines are no longer wrapped too short.
0.6.0 — 2023-03-22
- Runs can be selected by a commit SHA by using
--shaon the command line. - Retry if GitHub returns "502 - Bad Gateway".
0.5.0 — 2023-03-15
- Uses a
GITHUB_TOKENenvironment variable for authentication if it is defined.
0.0.2 — 2023-03-14
- Support more forms of repo URLs:
[email protected]:, without.git, etc. - Better error messages if the repo URL can't be parsed.
0.0.1 — 2023-03-13
First version
Development
The code is a bit messy and undocumented, and there are no tests. If you want to change the code, open an issue and let's talk about it.
Contributors:
- Ned Batchelder
- Hugo van Kemenade
- Rob Weir
Back Story
This started as a formatter for the output of gh run list from the gh
run command. Then I tried gh run watch, but wasn't happy with its
choices. So I wrote my own.