The 'thesis' project provides two GitLab scripts for setting up CI/CD. The default script is somewhat more complex, mainly designed for validating the template's functionality and PDF/A conformance in various use cases. The script typically needs slight modifications to be useful for producing a single document. Using this simplified script is recommended instead.

Other Git hosting services (e.g. GitHub) provide similar services, but the CI/CD pipeline configuration may require slight modifications.

Setting up GitLab CI/CD

The easiest way to set up GitLab CI/CD is to replace the provided .gitlab-ci.yml with the contents from .gitlab-ci-simple.yml:

$ mv .gitlab-ci-simple.yml .gitlab-ci.yml

Using the GitLab CI/CD

GitLab should automatically detect and run the CI/CD script after each commit if the file has the correct location (project root directory) and name (.gitlab-ci.yml). No further configuration required.

Note that the default configuration will inform all the GitLab project's owners via email upon a failed pipeline run.


CI/CD script structure

Next, let's take a closer look at the different sections in the CI/CD script.

Docker image

The CI/CD scripts delegate the document generation and validation to a custom TeXLive Docker container. See the project page for a detailed list of installed software.

While the purpose of this container is to facilitate LaTeX document generation in a CI/CD pipeline, the same image can also be used directly from the command line prompt or as a backend for other middleware.

To set up the environment in a GitLab CI/CD pipeline, configure the script to use the following image:

image: registry.gitlab.utu.fi/tech/soft/thesis/builder:latest

In case the image does not suit your needs, other prebuilt LaTeX Docker images such as these may offer a better starting point:

Build job

# build latex/thesis.tex -> latex/thesis.pdf using pdflatex
# shell-escape functionality is required by the minted package
build:
  stage: build
  script:
    - cd latex
    - latexmk -pdf --shell-escape thesis.tex
  artifacts:
    paths:
      - latex/thesis.pdf

Validation job

The Docker image contains a headless PDF/A validation tool that can be started by invoking (in a CI task) pdfa-validate <document-file>, e.g.:

$ pdfa-validate thesis.pdf

For a conforming document, built in the version=final mode, a successful run of the validation tool will print a single line starting with "PASS". See the PDF/A page for further instructions. A conforming document can be submitted to the UTUGradu system.

In the GitLab CI/CD, the validate job performs PDF/A validation for the resulting document. Note that the allow_failure directive is enabled here. This is due to the fact that the draft versions of the document may often fail and GitLab would otherwise spam all the project owners of each failed CI task by mail.

# a validation prints "PASS + something" if the file is PDF/A 
validate:
  stage: test
  script:
    - pdfa-validate latex/thesis.pdf|grep '^PASS'
  allow_failure: true

Deployment job

The pages job can be used to copy the generated PDF file to the GitLab Pages area (default location: https://USERNAME.utugit.fi/PROJECTNAME). This can be useful for automatically testing the build and producing the document for the supervisors. The deployment task can be left out if not needed.

In order to deploy the document, just copy the pdf file to the public/ directory inside the build directory. This is a bit problematic as there will be no index page and the exact URL must be used to access the file.

The following example demonstrates a bit more advanced deployment using sitegen. The application copies the document (assumption: thesis.pdf in the document root) to public/, then attempts to locate doc/thesis.md (useful for adding e.g. a changelog), converts the file to html, and finally composes an index.html that contains all the processed content along with a pdf.js viewer for browsing the document inside a browser. Note that the tool requires a compatible Docker image that contains either wget or curl, and optionally poppler-utils & pdfa-validator (both installed in the provided image).

pages:
  stage: deploy
  script:
    # if the docker image contains curl instead of wget, use this 
    # curl https://gitlab.utu.fi/tech/soft/tools/sitegen -o sitegen.jar
    - wget https://gitlab.utu.fi/tech/soft/tools/sitegen -O sitegen.jar
    - java -jar sitegen.jar -pdfjs
  only:
    - master
  artifacts:
    paths:
      - public/