Davide Gerosa

Github actions for latex

When writing LaTex papers with collaborators, I find it very useful to have a permanent URL that always points to the latest version of the compiled paper. People that are marginally involved can easily check the progress without messing up with the source files of those that are actually writing the paper.

I know overleaf provides a solution, but not everyone wants to use their web-based interface. I love my own editor… So, here is a solution with git and github actions that I find very convenient using

The quickest instructions

This is a template repository: dgerosa/writeapaper. You can click on “Use this template” and things will be set up for you. I also provide some templates of common journals in my field. The only thing you need to do is pick a template and move than into the “draft” directory.

After you created a new repository using this template, the one thing you need to make sure is that GitHub actions have write permissions. Go to Settings / Actions / General / Workflow permissions and tick the box Read and write permissions. Have fun!

Somewhat more manual instructions

  • Create your repository on github and put your latex paper there.
  • Copy this code I wrote into a directory called .github/workflows.
  • Edit the DIR and FILE variables in the script such that they point to your file. For instance, if your latex sources live in draft/main.tex, set DIR = draft and FILE = main.

Done, easy peasy. Now every time someone pushes something new to the repository, github does its magic and publishes the paper at a permanent URL of the form

https://github.com/[username]/[repositoryname]/blob/build/[filename].pdf

Enjoy your latex paper with github.

How does this work?

The code is here below. In practice, I’m telling github that every time one pushes it has to start a new virtual machine with ubuntu, install latex, compile paper and bibliography, and save the results. For how the github actions work, the result is first saved as an artifact and then moved to a dedicated orphan branch called build which provides the url we want.