Do you use LaTeX? I used to hate writing reports until I discovered LaTeX. However, one issue I had with it was that there was no easy way of sharing the PDF output online, especially if it’s something that’s a work in progress that you might want to edit and deploy frequently. This is particularly true in the case of CVs and resumes. In this article, I show you how to set up Continuous Integration [CI] of LaTeX projects with GitLab Pages. Once that’s set up, all it takes is a commit and a push, and voila, your finished work is published online within minutes! My own CV is deployed this way.
I’m assuming that you already understand the following:
I’m also assuming that you have a LaTeX file that you’d like to deploy. If not, you can experiment with this example repo, bluprince13/example-latex-ci-using-gitlab-pages, that I created.
Set up git repo
Let’s take a look at your repo before you get started. The LaTeX code is
main.tex file. You may have an image or two. A
.gitignore file is also recommended as it
tells git which files to ignore when making commits. Why not start with this
.gitignore template for LaTeX?
If you haven’t already, you need to initialise a git repository and commit your files using the commands below.
Create .gitlab-ci.yml file
GitLab, like GitHub, is a
web-based Git repository. Even though GitHub is more popular, GitLab has
built-in Continuous Integration/Delivery which is very straighforward to use.
This makes it perfect for our use case. Create a
.gitlab-ci.yml file in the
root of your repository with the code below. This file tells GitLab what to do
when you push a commit to it.
I’ve annotated the code to explain what’s going on. It’s split into two separate
jobs, which belong to the
deploy stages respectively. In the
build stage, we get hold of a Docker image for
LaTeX. Don’t worry if you don’t know what Docker is; it’s not crucial to
understanding what we’re trying to do. We then issue the command to build our
LaTeX file into a PDF. You can use whatever script you would use to do the build
on your computer -
lualatex etc. In the
deploy stage, we copy the PDF into a folder
public. Note that this
job has to be named
pages. This way GitLab
knows that you want to use the GitLab Pages feature.
Make sure you name the yml file correctly -
.gitlab-ci.yml. This is probably one of the easiest
mistakes you can make - speaking from experience!
You can read more about the
Let’s then add and commmit the
.gitlab-ci.yml file too.
Create and sync with GitLab project
Register for an account on
GitLab if you don’t already
have one and then create a GitLab
project. Once you
have a GitLab project, you can associate the git repo on your computer with it,
and then push the repo across to GitLab using the commands shown below. Since
the root of your repo has a
.gitlab-ci.yml file, it automatically triggers the
build process. You can watch the build and deploy process if you navigate to
/ CD > Pipelines on the GitLab page for your repo. If there are any errors, the
logs should help you get to the bottom of it.
Find the URL to the PDF output
You can find the URL for the homepage if you navigate to
Setting > Pages on
the GitLab page for your repo. If you had deployed a real website, the homepage
would have been available at
https://username.gitlab.io/projectname. Since you
only deployed a PDF file, visiting the homepage only results in a
error. However, the
main.pdf file is still available at
The example repo that I created is deployed at bluprince13.gitlab.io/example-latex-ci-using-gitlab-pages/main.pdf.
Only deploy tagged releases
You may not want to deploy every single commit. Sometimes, you may want to only deploy tagged releases once you’ve made enough changes and decide to make them public.
You can tag releases in git with the following command:
git tag -a 1.0 -m 'version 1.0'
You then need to modify the end of your
.gitlab-ci.yml to instruct GitLab
only to deploy tagged commits to GitLab Pages.
Don’t forget to commit and push your update to GitLab!
In this article, I showed you how to set up Continuous Integration for your LaTeX project using GitLab Pages. If you had any trouble following the instructions, please do leave me a comment and I’ll try to help. If you have any ideas for improvement, I’m all ears :)
I hope this article inspires you to explore Continuous Integration further for all your work. It’s pretty cool and let’s face it - we are all too lazy to do this stuff manually. :P