The showyourwork GitHub action¶
The showyourwork-action runs on GitHub Actions to automatically build your article on the cloud every time you push changes to the repository. Under the hood, this action clones your repository, installs conda
and Snakemake
, and runs your workflow to produce the figures and article PDF, which it then uploads to a separate branch on your repository. Importantly, everything is cached and all timestamps are preserved across builds, so this action will only re-run things that explicitly depend on the files that changed since the last time it ran.
This action is called in the workflow file .github/workflows/showyourwork.yml
, which is triggered on every pushed commit by default. Feel free to edit this file as needed, such as to include extra build steps, change the workflow triggers, or edit this action’s settings (see below). For more information on GitHub Actions workflow files, see here.
Inputs¶
The showyourwork-action accepts any of the following inputs, all of which are optional. These are provided using the with:
directive in the build
step of the .yml
file, one per line (see the example below).
action-path
¶
Optional Path to this action relative to the top level of the repo. You typically don’t have to change this unless you’ve reorganized the layout of your repository (and you know what you’re doing!). Default: showyourwork/showyourwork-action
.
article-cache-number
¶
Optional The showyourwork-action caches everything in your repository to speed up future builds. Sometimes, however, it’s useful to clear the cache, such as when something breaks. This can be done by incrementing this number, which tells the action which version of the cache to load. Default: 0
.
arxiv-tarball
¶
Optional Build a tarball for easy ArXiV submission? This tarball contains the article PDF, the rendered figures, and all the input files needed to compile the manuscript using a standard LaTeX compiler. The tarball is then pushed to the same branch as the article output (see force-push
below). Default true
.
conda-cache-number
¶
Optional Bump this number to reset the conda
cache. The behavior is similar to that of article-cache-number
above. Default: 0
.
conda-url
¶
Optional Exact url pointing to the conda
install script. This always points to the latest conda
installer, so you probably don’t need to change this. Default: https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
.
github-token
¶
Optional A token for access to GitHub (e.g. secrets.GITHUB_TOKEN
). Do not set this value explicitly – always use a secret! Default: ${{ github.token }}
(usually set automatically)
install-tex
¶
Optional Install the TinyTex
distribution in addition to tectonic
? Useful if LaTeX
is required by matplotlib
. Default: false
.
output-branch-suffix
¶
Optional Force-push output to branch <current-branch>-<output-branch-suffix>
? For example, if you’ve pushed a commit to the main
branch, this action will by default compile your paper and force-push the output (the paper PDF as well as the ArXiV tarball, if enabled) to the branch main-pdf
. The force in force-push means this is not a typical git
commit, as it will overwrite everything on that branch. This way, your repository won’t get bloated over time with tons of committed output history. Default: pdf
.
tex-packages
¶
Optional TeX packages to install, one item per line. Matplotlib requires at least type1cm
and cm-super
(default).
verbose
¶
Optional Enable verbose output and debug messages? Default: false
.
Example usage¶
Below is a complete example of a .github/workflows/showyourwork.yml
file. Note that the repo should be checked out with fetch-depth: 0
and submodules: recursive
to ensure the action works as intended.
on: push
jobs:
showyourwork:
runs-on: ubuntu-latest
name: Build the article PDF
steps:
- name: Checkout
uses: actions/checkout@v2
with:
fetch-depth: 0
submodules: recursive
- name: Build the article PDF
id: build
uses: ./showyourwork/showyourwork-action
with:
article-cache-number: 0