14

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?

  • 1
    Would you mind if I changed the title to be a bit more generic ("(La)TeX" instead of "LaTeX")? – TeXnician Nov 11 '18 at 16:51
  • 1
    No, I wouldn’t mind at all – JBantje Nov 11 '18 at 16:54
  • 1
    I wrote a post about exactly this - vipinajayakumar.com/… – bluprince13 Jan 18 at 0:39
8

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.

  • 2
    you don't need to use docker to run latex on travis of course you could just use apt-get to get a tex installation in the vm or (as we do for the core latex test suite) get the upstream texlive installer and install a minimal texlive scheme, you can cache the resulting installation directory so there is little overhead after the first time. – David Carlisle Nov 11 '18 at 17:24
  • @DavidCarlisle It's right you don't need docker, however I think the main advantage of docker is that the build config files needed become much smaller, at least they did for me with Travis (compare this .travis.yml with this folder). But of course for the core latex test suite that's not important because you know what you're doing ;) – PHPirate Jan 18 at 6:44
8

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"
3

This answer provides examples for CI files that I use to compile LaTeX documents on Gitlab CI. They use the sumankhanal/texlive-2018 image to provide a basic TeX Live installation including Pygmentize. 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: sumankhanal/texlive-2018

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: sumankhanal/texlive-2018

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 a smaller image file have a look at my answer here. That reduces the image size to about 1.7 GiB.

1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.