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?
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It only takes a minute to sign up.Sign up to join this community
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.
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.
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.
.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.
(In comparison to the approach with Travis CI and GitHub mentioned earlier)
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.
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
in a Docker file or for GitLab CI
lmtx if you want to use LuaMetaTeX.
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
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.
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.
.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.