Compiling (La)TeX files automatically with GitLab CI

Question

Inspired by this question about compiling LaTeX files with Travis CI:

How can GitLab's integrated CI feature be used to build (La)TeX documents?

Answer 1

Backstory

I maintain a huge repository of lecture notes written in LaTeX, once hosted on GitHub. Now it can be found HERE on GitLab.com. I use Continuous Integration to automatically compile all relevant .tex files and upload them to an enterprise-scale OwnCloud installation.

I used a Travis CI setup as in the linked question a few years back.

How does GitLab CI work in general?

If activated in a repo, GitLab can run so called "pipelines" when new commits are pushed. The CI properties are mainly handled by the .gitlab-ci.yml configuration file, which allows for a ton of customisation: several stages (like building, testing, deployment) may be defined, branches can be handled separately, secret variables, …

This configuration file also specifies, what commands/scripts are to be run in a CI job. But which machine actually runs these scripts? – This is handled by "runners", which are assigned to a repo. Any computer can become a runner by installing the GitLab Runner software, which is available for all major operating systems or even as a Docker container. The results (console log and maybe artefacts) are sent back to GitLab by the runner. There are public runners operated by GitLab.com, which may be used freely under certain limitations (and aren't very helpful for LaTeX, I assume).

For more details, see the documentation of GitLab.

My Setup for Compiling .tex files

On my home server I have the runner software installed (which, on Linux, adds a user "gitlab-runner"), which is easy to maintain via apt. Furthermore I installed TeXlive without the package manager (aka "the recommended way") and made sure that the user "gitlab-runner" can use it.

From the .gitlab-ci.yml file a makefile is called, which in turn calls a bash script for the compilation of the several files. Empowered by the caching feature, latexmk is only run for modified files and only the updated files are reuploaded via WebDAV to the aforementioned OwnCloud installation.

Details and my .gitlab-ci.yml file can be found in the repo linked above.

Pros and Cons of this GitLab CI solution

(In comparison to the approach with Travis CI and GitHub mentioned earlier)

Pros:

• the CI jobs are executed very fast, since there is no Docker overhead and the runner almost immediately starts the actual compilation
• the caching prevents unnecessary compilation
• a full featured TeXlive installation is used
• imho GitLab is preferable over GitHub for various reasons (self hosted installation etc.)
• Extremely customisable (up to the TeXlive installation)

Cons:

• the need to maintain a server (energy consumption of a home server, hosting fees for a webserver, but theoretically some office PC could do the job as well)

My Verdict

Common CI services like Travis are not perfectly suited for the niche application LaTeX, because of the docker shenanigans needed to get it done – GitLab's integrated CI feature allows for a tailored solution, which is not only faster but more powerful.

If there are further questions feel free to ask.

Answer 2

Beware: This is a post about ConTeXt

Apart from LaTeX you may want to compile ConTeXt documents using Gitlab CI. That's very easy as well. Simply use the install script provided by ConTeXt standalone (the following CI configurations will download the beta version of ConTeXt).

Basic example compiling a ConTeXt document:

stages:
  - build

build:
  stage: build
  image: debian:unstable
  script:
    - apt-get update && apt-get install -y wget rsync unzip && rm -rf /var/lib/apt/lists/*
    - mkdir context && cd context
    - wget http://minimals.contextgarden.net/setup/first-setup.sh
    - sh ./first-setup.sh --modules=all --context=beta --engine=luatex
    - . tex/setuptex
    - cd ..
    - context document.tex
  artifacts:
    paths:
      - ./*.pdf

More sophisticated installing custom fonts (again, I will use Fira Code from the git repo):

stages:
  - build

build:
  stage: build
  image: debian:unstable
  script:
    - apt-get update && apt-get install -y wget rsync unzip git && rm -rf /var/lib/apt/lists/*
    - mkdir context && cd context
    - wget http://minimals.contextgarden.net/setup/first-setup.sh
    - sh ./first-setup.sh --modules=all --context=beta --engine=luatex
    - . tex/setuptex
    - cd .. && mkdir fonts && cd fonts
    - git clone https://github.com/tonsky/FiraCode firacode
    - export OSFONTDIR="/usr/local/share/fonts;$HOME/.fonts;`pwd`"
    - mtxrun --script fonts --reload
    - cd ..
    - context document.tex
  artifacts:
    paths:
      - ./*.pdf

For the sake of completeness: Here's a docker file you might want to use to have a certain ConTeXt version as a container for multiple projects:

FROM alpine:latest

RUN apk update && apk add wget rsync unzip libgcc

RUN mkdir context && cd context && wget http://minimals.contextgarden.net/setup/first-setup.sh && \
        sh ./first-setup.sh --modules=all --context=beta --engine=luatex

ENV PATH "/context/tex/texmf-linuxmusl-64/bin:$PATH"

Update Dec. 2019: The Island of TeX offers ConTeXt standalone images, so all you need as image is something like

FROM registry.gitlab.com/islandoftex/images/context:beta

in a Docker file or for GitLab CI

image: registry.gitlab.com/islandoftex/images/context:beta

replacing beta with lmtx if you want to use LuaMetaTeX.

Answer 3

This answer provides examples for CI files that I use to compile LaTeX documents on Gitlab CI. They use the latest TeX Live image from the Island of TeX to provide a basic TeX Live installation including Pygmentize (they provide snapshots for older TeX Live distributions as well). If you want to use one of these, simply put them into your .gitlab-ci.yml file.

This is a very simple alternative, if you are willing to compile your document using pdflatex or arara.

image: registry.gitlab.com/islandoftex/images/texlive:latest

before_script:
  - apt-get update && apt-get install -y openjdk-8-jre && rm -rf /var/lib/apt/lists/*
  - tlmgr update --self --all

build:
  script:
    - arara -lv document.tex
  artifacts:
    paths:
      - ./*.pdf

You may even do fancy font installations (in this case pulling Fira Code using git) and then use them within your document:

image: registry.gitlab.com/islandoftex/images/texlive:latest

before_script:
  - apt-get update && apt-get install -y openjdk-8-jre git && rm -rf /var/lib/apt/lists/*
  - git clone https://github.com/tonsky/FiraCode firacode  && cp firacode/distr/otf/*.otf /usr/local/share/fonts/
  - fc-cache -fv
  - tlmgr update --self --all

build:
  script:
    - lualatex document.tex
  artifacts:
    paths:
      - ./*.pdf

If you want to build your own small image file have a look at my answer here. That reduces the image size to about 1.7 GiB.

Answer 4

For my cv I use the script below:

compile_pdf:
  image: aergus/latex
  script:
    - latexmk -r .latexmkrc -pdf 'resume.tex' -jobname=resume
  artifacts:
    paths:
      - ./build/resume.pdf

This is saved in a file called .gitlab-ci.yml and will build a new version every time a new commit is made.

My .latexmkrc contains the following:

$latex = 'latex  %O  --shell-escape %S';
$pdflatex = 'lualatex  %O  --shell-escape %S';
$out_dir = 'build';

I use the --shell-escape command for the minted package.