Continuous Integration of LaTeX projects with GitLab Pages

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.

Prerequisites

I’m assuming that you already understand the following:

• Writing and building LaTeX documents on your computer
• Using git for version control

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 in the 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?

• .gitignore
• main.tex
• myfigure.jpg

If you haven’t already, you need to initialise a git repository and commit your files using the commands below.

123

git init
git add .
git commit -m "Initial commit"

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 build and 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 - pdflatex, lualatex etc. In the deploy stage, we copy the PDF into a folder called 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 .gitlab-ci.yml file here.

 1 2 3 4 5 6 7 8 9101112131415161718

compile_pdf:
  stage: build
  image: timnn/texlive  # use a Docker image for LaTeX from https://hub.docker.com/
  script: pdflatex main.tex  # build the pdf just as you would on your computer
  artifacts:
    paths: 
      - main.pdf  # instruct GitLab to keep the main.pdf file

pages:
  stage: deploy
  script:
    - mkdir public  # create a folder called public
    - cp main.pdf public  # copy the pdf file into the public folder
  artifacts:
    paths: 
      - public  # instruct GitLab to keep the public folder
  only: 
    - master  # deploy the pdf only for commits made to the master branch 

Let’s then add and commmit the .gitlab-ci.yml file too.

12

git add .
git commit -m "Added .gitlab-ci.yml file"

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 CI / 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.

12

git remote add origin https://gitlab.com/username/projectname.git
git push -u origin master

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 404 error. However, the main.pdf file is still available at https://username.gitlab.io/projectname/main.pdf

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.

1234

  only:
    - tags  # Only for tagged releases (e.g. 0.1, 1.0)
  except:
    - branches  # Only for the master branch 

Don’t forget to commit and push your update to GitLab!

Conclusion

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 got started by reading this blog myself, but it didn’t go into the deployment via GitLab Pages bit. It’s also worth checking out the GitLab Pages User Documentation.

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