HowToGitLabRunner

The goal of this project is to demonstrate how to use GitLab-Runner with a very simple use case: transform this README.md into README.pdf with pandoc.

Preamble

Doing this demo taught us some important lesson: we first tried to build the PDF and push it into this repo. While it seems feasible, it not a good idea. First of all, you want to keep your commits atomic, meaning that you don't want a commit creates a new commit automatically. Secondly, the CI/CD mechanisms is here to build and/or deploy a specific commit to other systems/environment, not modifying the current one. Finally, we choose to do it the following way:

1. One modify the README.md file;
2. It trigger the build to create the README.pdf file;
3. Then, a release is created, association the README.pdf file to it.

That way, the things are kept as close as possible to a standard dev/stage/prod environment.

Before diving into it, you may want to check the documentation and some real world examples.

Setup the "shell" runner

First of all, you need a runner on a machine. The installation process is described here: https://docs.gitlab.com/runner/install/

It creates the gitlab-runner user on your system. On some Linux, you may want to remove the ~/.bash_logout file to avoid the issue 4092 — thanks me later.

The last step explains how to register the runner with sudo gitlab-runner register. Answer the questions (the runner key is found on your Project > Settings > CI/CD > Runner). You may want to check the runner options (for example "Run untagged jobs"). It will create the /etc/gitlab-runner/config.toml file which looks like that:

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "X1"
  url = "https://gitlab.epfl.ch"
  token = "tQqmy2TFSZoJQfm-83_W"
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

Check and edit the .gitlab-ci.yaml

The whole pipeline/stage/job configuration stands in the .gitlab-ci.yaml file. A lot of documentation is provided by GitLab: https://docs.gitlab.com/ce/ci/.

In short, this file defines the pipeline process, which contain stages. A stage can contains jobs, which describes what to do. Jobs can be parallel and manual.

Note that if you want to keep "produced" files between jobs, you have to use the artifacts system.

The file of this project define 4 stages:

• test → just prints out some env variables.
• build → creates the README.pdf.
• deploy → creates the release via the deploy.sh script. Need a variable.
• control → final steps, does nothing but echoing a string.

Set the variable

To be able to use the API to create a release, you need to have a Personal Access Tokens which can be created in your personal account. In the deploy.sh script, it's used as the MY_TOKEN variable. Once you get the token, there are 2 ways to use it:

• define it into the project (Project > Settings > CI/CD > Variables), which means that other persons of the project will use it.
• define it when manually launching the pipeline: only you will be able to use it but automatic trigger will fail.

This is OK for this demo or small projects, but a better way to do it is to create a "bot" user to whom you give some right on your repository and create the personal access token from it.

Observe

Now it time that you try out the pipeline. Either change something to this file (I'm sure there's a lot of errors and missing/incorrect information) and push to the repo, or go into your project CI/CD pipelines and use the "Run pipeline" button.