Build LaTeX documents with the GitLab CI

For fun and reproduceability I set up a CI build for my LaTeX documents. I used it mainly for my thesis.

Overview

This guide is targeted on people who already have a GitLab Runner with Docker support up and running. I will not provide information on how to get there. This topic is covered by lots of other guides all over the internet.

I guess the main motivation for this is having a defined building environment without an IDE like TexStudio beeing involved and doing some parts of the job for you.

This starts with having a local Makefile or a sequence of bash commands to build the documents.

But first lets declare what packages must be available:
On my laptop I installed the texlive-full packages. In my experience it includes all dependecies you use in a normal use case.

Makefile

Next have a look at the Makefile I am using. I use latexmk inside to create the parts like blibliography and so on and the only seprate build object is the gloassary.

You can skip using a Makefile altogether if your use-case is simpler and you have just one or two bash comands.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

.PHONY: pdf all clean

all: pdf glossaries pdf

%.tex: %.raw
    ./raw2tex $< > $@

%.tex: %.dat
    ./dat2tex $< > $@

glossaries:
    makeglossaries bachelorthesis

pdf: bachelorthesis.tex
    latexmk -pdf -pdflatex="pdflatex" -use-make bachelorthesis.tex

clean:
    latexmk -c

CI-File

Finally there is the CI file itself.

All together my .gitlab-ci.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

compile_pdf:
  variables:
    GIT_SUBMODULE_STRATEGY: normal
  image: blang/latex:ctanfull
  script:
    - cd dir
    - make
  artifacts:
    paths:
      - dir/thesis.pdf

Let’s take it apart:

1
2

  variables:
    GIT_SUBMODULE_STRATEGY: normal

I use submodules in my project, if you don’t, leave this out. It tells the Runner to checkout the submodules recirsively.

1

  image: blang/latex:ctanfull

Above I discussed the build environemnt that is neccessary. This comand specifies a Docker image with the texlive-full installation. This is the largest image with about 5GB uncompressed. There are others available which may be enough for you and which are smaller.

If you do not want to use Docker you can als run this on GitLab Shell or SSH runners. You just have to install the texlive packages on those hosts by hand as a preliminary.

1
2
3

  script:
    - cd dir
    - make

The actual build command. Make sure you change into the correct directoy before running make or have the Makefile in the parent directory.

1
2
3

  artifacts:
    paths:
      - dir/thesis.pdf

This advises the Runner to store the compiled pdf file with the GitLab artifacts. It allows you to download the pdf through the web frontend lateron.

In summary this may be a very simple example – but as always a lot of power comes with automation.