Making life simpler with LaTeX and GitHub Actions

The GitHub Actions has been a great asset for any and every possible project that requires on-the-fly integration checks, deployment, or even rick-rolling when there is a new issue submitted to the repo.

One exciting application, though, is the ability to integrate the actions to generate PDF (or PS) for a LaTeX source seamlessly. It is especially useful when collaborating with multiple authors responsible for different sections of the paper. The workflow in such a collaborative environment bodes well for productivity for all authors. For instance, one can check against typos, logical errors, or even style issues when submitting pull requests towards the main branch.

Preparations

The first (or pre-first) step is to have a required LaTeX template and a Git repository hosted on GitHub (to leverage the Actions). Each template has a specific structure that needs to be adapted towards the script; in this post we consider the following configuration:

.
|-sections 
    | introduction.tex
    | related_works.tex
    | problem.text
    | solution.tex
    | experiment.tex
    | results.tex
    | conclusion.tex
|- main.tex
|- references.bib

The most important part of any LaTeX structure is to have the main.tex file in the root directory of the repository.

GitHub Actions

There are a lot of different GitHub actions that can be used for compiling LaTeX to PDF available on the GitHub marketplace []. The simplest among them is the latex-action, which is trivial to integrate and use.

The actions generates PDF file from the provided LaTeX file using a workflow as shown below:

name: Build LaTeX document
on: 
    push:
        branches: [ main ]
    pull_request:
        branches: [ main ]
jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Git repository
        uses: actions/checkout@v2
      - name: Compile LaTeX document
        uses: xu-cheng/latex-action@v2
        with:
          root_file: main.tex

This would only compile the LaTeX file but won’t be sufficient to have a complete automated workflow. We create two more jobs, one being to create a release and the second to upload the release. The former creates a release on the GitHub repository, and the second one uploads the PDF file to the release page. To do this, we can extend our actions script as follows:

name: Build LaTeX document
on: 
    push:
        branches: [ main ]
    pull_request:
        branches: [ main ]
jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Git repository
        uses: actions/checkout@v2
      - name: Compile LaTeX document
        uses: xu-cheng/latex-action@v2
        with:
          root_file: main.tex

      - name: Create Release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: $
        with:
          tag_name: $
          release_name: Release $
          draft: false
          prerelease: true

      - name: Upload Release Asset
        id: upload-release-asset 
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: $
        with:
          upload_url: $ 
          asset_path: ./main.pdf
          asset_name: main.pdf
          asset_content_type: pdf

Upon successful run, it would build a PDF file from the LaTeX file, create a release and upload the file for release. And that’s it; you can now successfully serve a compiled PDF of your LaTeX without the need to compile it locally.