tips and tricks github actions

Automate PDF compilation with Github Actions

(by @EduardoFAFernandes, discussion #285)

Hello everyone

A couple of days ago I wanted to change something on my thesis and generate the pdf accordingly but did not have my machine with me. I found out that you can use GitHub actions to automatically compile the PDF when a new commit is pushed to the repository. I found this useful and may come in handy for some of you, so here are the instructions on how to do it.

Instructions

1. Create a new file .github/workflows/<filename>.yaml.
2. Paste the following:

name: Build LaTeX document

on:
  push:
    branches:    
      - 'main'

jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:

      - name: Checkout Git repository
        uses: actions/checkout@v2

      - name: Build LaTeX document
        uses: dante-ev/latex-action@latest
        with:
          root_file: template.tex

      - name: Commit changes
        uses: EndBug/add-and-commit@v8
        with:
          author_name: AuthorNameHere
          author_email: [email protected]
          message: 'Auto-updating PDF File'
          add: 'template.pdf'

3. Commit changes and push
4. Profit 😄

Results

After pushing this file to the main branch head to your GitHub actions tab and a new workflow should be running. When the workflow finishes, the main branch should have a new commit with an updated PDF file.

Customization

This script fits my purpose but you may want to change something so here are a couple of important things to guide you.

Change the branch trigger

In this case the main branch is used to trigger the workflow but you may want something else, for example:

• Change the name of the branch
• Add another branch trigger
• Make any branch trigger compilation

Here are some useful links: Other push trigger options Other triggers

Notes:

• When testing this action I recommend the creation of a new branch for testing it, so a change of name is useful.
• Only using the main/master or a dedicated compilation branch will allow you not to compile every small commit you make only the ones you intend to compile.

LaTeX Compilation options

To compile the file the action LaTeX compilation is used. The action is well documented you should be able to find your options there like flags and compiler engine.

Note: I did try to use the make command to compile the project but wasn't successful.

Saving the file

Finally, to save the PDF this file uses the action add-commit Once again this action is well documented and you should be able to find the options you need in the documentation.

If you don't want to create a new commit there is an other option. You may attach a file to the action result as an artifact with the action upload-artifact. This will be visible in the action's summary page.

Final remarks

I advise against using this option as substitute for a good development environment, local or cloud based. Only as helpful complement. Debugging on GitHub sounds like a nightmare.

Running an action takes resources be considerate and use when there is a need for automatic compilation, you may for example create a dedicated branch dedicated to automatic compilation.

As of writing free users have access to 2000 minutes of processing time a month. You can check your limits and usage in the Personal Billing page. The minimum amount of time for 1 run should be at least 2 minutes plus your project compilation time.

To learn more about GitHub actions refer to the original documentation

I wasn't sure if I should add this to the wiki or even where to put it, if you think this is relevant feel free to add it or suggest where I could add it.

Hope this is proves useful.

Cheers.