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/