|Maximilian Keßler 30db8f7038|
GitLab CI Template
What you get
This template is intended to quickly set up a new LaTeX project with GitLab CI, that is, automatic compilation of your LaTeX document. Unfortunately, it will take some extra time on first usage to set up the GitLab runner, but you only have to do this once.
The created project has the structure of the
template folder present in this repository.
In particular, it is structured as follows:
- There is a main LaTeX file. This will include all other files, compiling this gives the desired output
- There is some auxiliary style file, custom for this project. The master file will include this and only this style file. Essentially, this is a preamble at some dedicated place
- Additionally, we set up the LatexPackagesBuild repository as a submodule to have custom packages available
- We use latexmk to compile our document. A
.latexmkrcis provided that makes
LaTeXfind the custom packages located in the submodule
- As another measure for dealing with the imports, there is a script file
source ./export_texinputs.shwill set the
LaTeXinput path correctly, so that also
pdflatexand friends will find the packages in the submodule.
- We provide a Makefile as an easy compile-interface. This also manages automatically initializing the submodule before compiling if it is not yet checked out. This ensures that
makeworks in a fresh copy of the closed repository without explicitly having dealt with the submodule, so the work should be accessible for others easily.
- A standard
.gitignorefor LaTeX projects is provided.
- A standard
README.mdis provided, containing links to the CI.
The gitlab CI depends on the following assumptions:
- The repository will be hosted on a GitLab instance (not necessarily gitlab.com)
- You have a gitlab runner registered for your (new) project or any group that the project is a member of
- You enabled GitLab pages for your (new) project
It will then auto-compile the latest version of your document with each commit or tag and publish it at your GitLab pages environment so you (and possibly others) can directly download it without having to clone and build the repository themselves.
To use this template:
- clone it to some dedicated place and give it the name of your new project:
git clone https://gitlab.com/latexci/templates/gitlab-ci-template.git mynewproject
- enter your data in the
configfile of the template (located in the root directory)
WARNING: execution of the
init.sh shell script will IRREVOCABLY DESTROY the obtained copy of the template, including its git history, and set up your new project with an initial git commit. DO NOT run this
init.sh if you modified the template and do not have a copy of it, or you risk losing your repository. The author takes no responsibility for such misusages.
For correct usages, this is of course the correct behaviour.
The data to be entered in the
config file is as follows:
mainfile: This is the name of your main
LaTeXfile, without extension
course: A plaintext name of your course. Will be present in the
README.mdand set as title of the LaTeX file
stylefile: The name of the custom style file / preamble, without extension
repo: A url to the gitlab pages environment of your new project. This requires you to know the exact name of the GitLab repository you intend to host the new repository. It is given in one the following forms:
To make the template work out correctly, the trailing slash is important.
term: Some plain-text description of the term of the lecture notes.
Enable gitlab runner
If you do not use a public runner (the author is not aware of any that are capable of handling LaTeX):
- If you did not already do so, or did for a whole group, now is the time to add your custom GitLab runner to your project. Refer to [Register your runner](README.md#Register your runner).
- Explicitly disable the usage of public runners in your
Settings -> CI/CD -> Runnerssection. Otherwise, your CI will fail and GitLab will ask you for a credit card to prevent misuse of public runners (which you don't use anyways, go blame GitLab for that antifeature).
Enabling GitLab pages
Finally, do not forget to enable GitLab pages for your project (as far as the author is aware, this is only the default for public projects). Go to
Settings -> General, expand the
Visibility, project features, permissions tab, and activate the
Pages switch (second from bottom). You can also set the access level there if you wish.
Refer to the GitLab pages documentation for full details on how this works.
If you have not done so yet, refer to [setting up ci](README.md#Setting up GitLab CI) section to set up a GitLab runner.
An example project generated with the configuration
#!/bin/bash mainfile='2022_Example_Course' course='Example Course' stylefile='example' repo='https://latexci.gitlab.io/examples/gitlab-ci-example' term='summer term 2022'
is available (without any further modification) as gitlab-ci-example.
Setting up GitLab CI
Refer to the GitLab Runners Documentation for full details on how GitLab runners work. If you want to set up one yourself, for LaTeX projects, the author recommends the following:
Set up docker container for compilation
- Set up your GitLab runner with the
dockerexecuter. Then your runner will use a container for a controlled environment, refer to GitLab docker installation for installation procedures.
- Install docker
- Install some docker image that is able to build your project. For a default latex runner, the author recommends the aergus/dockerfiles, it features a full TexLive installation and is availabe via DockerHub, so that your runner can automatically pull your image.
- If you also want to have python and the
treeutility built into your image, you can use kesslermaximilian/dockerfiles, which is just a fork of the former adding this stuff.
For a custom docker image (not on DockerHub) only:
- Make sure you build your docker image and have it listed in the
docker imagesoutput under the name you specified when setting up your
- You will have to edit the
config.tomlof your GitLab runner, since by default, it will try to pull from DockerHub. For this, add an entry
pull_policy = ["never"]in the
[runners.docker]section, this will make your runner use local docker images.
Install the GitLab runner software
This is covered in the documentation quite well. The author recommends also installing the runner in a container, you can then easily run this in the background, but of course, choose as you like.
Register your runner
When registering your runner, it is important that you specify the
latex tag (you will be prompted for a list of tags) so that GitLab will correctly find and use your runner.
Technically, you could also use some other tag, but this is the one the author chose for this template.
You will also have to provide the name of the docker container you intend to run your LaTeX in, so this will be (following above examples)
As you might have noticed, The template script is written in bash and thus not (trivially) portable to Windows. The author does not care about that and sees little reason to do anything about it.
The author thanks Josia Pietsch for help with setting up and testing this template. The author also thanks StackOverflow, because he actually has no clue about