Metadata-Version: 2.1
Name: watchgha
Version: 2.1.0
Summary: Watch GitHub action runs
Author-email: Ned Batchelder <ned@nedbatchelder.com>
License: Apache-2.0
Project-URL: Source code, https://github.com/nedbat/watchgha
Project-URL: Issue tracker, https://github.com/nedbat/watchgha/issues
Project-URL: Mastodon, https://hachyderm.io/@nedbat
Project-URL: Funding, https://github.com/sponsors/nedbat
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: click
Requires-Dist: dulwich
Requires-Dist: exceptiongroup
Requires-Dist: httpx (>=0.24.0)
Requires-Dist: rich
Requires-Dist: trio

########################
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`_:

.. code-block:: shell

    $ pipx install watchgha

Now 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:

.. code-block:: ini

    [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
=====

.. [[[cog
    import os
    import subprocess
    import textwrap
    command = "watch_gha_runs --help".split()
    env = dict(os.environ, COLUMNS="72")
    output = subprocess.check_output(command, env=env)
    print()
    print(".. code-block::")
    print()
    print("    $", *command)
    print(textwrap.indent(output.decode(), "    "))
.. ]]]

.. code-block::

    $ 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.

.. [[[end]]] (checksum: 145e6947de009772786baa046962e235)


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:

..
    How to make the animated gif:
      - branch in coverage.py
      - comment out pypy in testsuite.yml
      create window 80x24
      copy "watch_gha_runs --wait-for-start --poll=5"
      g ampf; asciinema rec --overwrite watch.cast
      paste the command
      exit the shell when it's done
      $ agg --speed=5 --font-family="Monego,Symbola" --font-size=18 watch.cast watch.gif

.. image:: https://raw.githubusercontent.com/nedbat/watchgha/main/watch.gif

.. code-block::

    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
=========

.. scriv-start-here

2.1.0 — 2023-07-05
------------------

- Implicit .netrc authentication stopped working, but has been fixed. Thanks,
  `Rob Weir <pull 11_>`_.

.. _pull 11: https://github.com/nedbat/watchgha/pull/11


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-start`` will 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.

.. _issue 7: https://github.com/nedbat/watchgha/issues/7
.. _issue 8: https://github.com/nedbat/watchgha/issues/8
.. _issue 10: https://github.com/nedbat/watchgha/issues/10


1.0.0 — 2023-04-15
------------------

- The ``--poll`` option 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 ``--sha`` on the command line.

- Retry if GitHub returns "502 - Bad Gateway".


0.5.0 — 2023-03-15
------------------

- Uses a ``GITHUB_TOKEN`` environment variable for authentication if it is
  defined.


0.0.2 — 2023-03-14
------------------

- Support more forms of repo URLs: ``git@github.com:``, without ``.git``, etc.

- Better error messages if the repo URL can't be parsed.


0.0.1 — 2023-03-13
------------------

First version


.. scriv-end-here

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.

.. _gh run command: https://cli.github.com/manual/gh_run
.. _git alias: https://www.atlassian.com/git/tutorials/git-alias
.. _pipx: https://pypi.org/project/pipx/
