bowlby

The upload-artifact action allows you to save files from an actions workflow - stuff like test results. Unfortunately it's not yet possible to actually look at those files without downloading a zip and manually extracting it. I am very lazy, so that miniscule effort is entirely intolerable when I just want to see what the test failure is.

Enter bowlby, an application that does the tedious downloading and unzipping bits and lets you freely browse the contents of the artifacts.

We've got an instance running at https://bowlby.flowty.dev/self/ that allows access to the artifacts in this project. You can browse the latest test results at

• bowlby in isolation
• browser in isolation
• github in isolation
• integrated system

If you click through those you'll get sense of how it works and confirmation that it does work.

Build

It's a standard java/maven project. Check it out and run mvn package. This will produce an executable jar at /app/target/bowlby - copy that to wherever you want.

If you don't have time for that nonsense then you can download the compiled jar from the artifacts on this workflow. If your risk-tolerance extends to "save-as"-ing on strange links and executing the results, then have at it.

Execution

Run it with java -jar bowlby. If you're running on linux then you can invoke it directly with ./bowlby.

By default it'll come up on port 56567 - you should see console output to that effect.

Usage

Point a browser at the instance (e.g.: if you're running it locally then http://localhost:56567) and the root page will show a form that accepts two types of links:

• Links to specific artifacts, such as you see at the bottom of the summary page of a workflow run (e.g.: https://github.com/therealryan/bowlby/actions/runs/10391396242/artifacts/1812359413) Bowlby will redirect you to a view of the files in that particular artifact. This set of flows illustrates that operation
• Links to workflows, such as you'd find on the "Actions" tab (e.g.: https://github.com/therealryan/bowlby/actions/workflows/testing.yml) Bowlby will redirect you to a page with stable links that display the files of the most recent artifacts of that workflow on the repo's default branch. This set of flows illustrates that operation

You can integrate your bowlby instance directly into your actions by:

1. Giving your upload-artifact step an id (for example)
2. Adding a step that uses the artifact ID output of that step to emit a markdown link into the job summary (for example).

This puts a link to the browsable artifact contents into the job summary, saving you the onerous burden of copy-and-paste.

Configuration

Bowlby is configured via environment variables with command-line argument overrides:

Usage: bowlby [-h] [-a=<artifactValidity>] [-c=<contextPath>] [-d=<cacheDir>]
              [-g=<githubApiHost>] [-i=<iconBehaviour>] [-l=<latestValidity>]
              [-p=<port>] [-r=<repositories>] [-t=<authToken>]
A browsable proxy for github action artifacts
  -a, --artifactValidity=<artifactValidity>
                            An ISO-8601 duration string, controlling how long
                              an artifact zip is preserved for.
                            Defaults to 'P3D', which means a downloaded
                              artifact zip will be deleted 3 days after its
                              most recent access.
                            Overrides environment variable
                              'BOWLBY_ARTIFACT_VALIDITY'
  -c, --context=<contextPath>
                            Controls the path at which bowlby assumes it is
                              being served.
                            If you're accessing bowlbly directly then you can
                              leave this blank (the default), but if you're
                              proxying requests to your webserver at
                              `/some/path` to hit your bowlby instance then
                              you'll want to set this to `/some/path` so that
                              bowlby can issue redirect responses correctly.
                            Overrides environment variable 'BOWLBY_CONTEXT_PATH'
  -d, --dir=<cacheDir>      The directory in which to cache artifacts.
                            Defaults to 'bowlby' under the system's temp
                              directory.
                            Overrides environment variable 'BOWLBY_DIR'
  -g, --github=<githubApiHost>
                            The hostname to target with github API requests.
                            Defaults to 'https://api.github.com'
                            Overrides environment variable 'BOWLBY_GH_HOST'
  -h, --help                Prints help and exits
  -i, --icon=<iconBehaviour>
                            Controls the system tray icon. Choose from NONE,
                              STATIC or DYNAMIC.
                            The dynamic icon will give a visible indication of
                              request-handling activity
                            Overrides environment variable 'BOWLBY_ICON'
  -l, --latestValidity=<latestValidity>
                            An ISO-8601 duration string, controlling how long
                              the latest artifact results are cached for.
                            Defaults to 'PT10M', which means it could take up
                              to 10 minutes for the link to the latest artifact
                              to reflect the results of a new run.
                            Overrides environment variable
                              'BOWLBY_LATEST_VALIDITY'
  -p, --port=<port>         The port at which to serve artifact contents.
                            Defaults to 56567
                            Overrides environment variable 'BOWLBY_PORT'
  -r, --repos=<repositories>
                            A comma-separated list of 'owner/repo' pairs,
                              identifying the set of repositories that bowlby
                              will serve artifacts from.
                            Defaults to empty, which means _all_ repos will be
                              served.
                            Overrides environment variable 'BOWLBY_GH_REPOS'
  -t, --token=<authToken>   The github authorisation token to present on API
                              requests.
                            Overrides environment variable
                              'BOWLBY_GH_AUTH_TOKEN'

Note that:

• You'll need to give it an API auth token. A fine-grained personal access token with no special permissions works fine.
• If you're going to run an instance exposed to the internet, I'd strongly recommend limiting which repositories are addressable via BOWLBY_GH_REPOS.