How to set up a GitLab runner¶
GitLab runners are software agents which run GitLab continuous integration jobs on private servers. They are usually used to build, test and deploy software products.
Wherever possible, Beautiful Canoe projects should use the Docker infrastructure that is available on GitLab to execute CI/CD jobs, and avoid installing runners on our own servers. However, where a project needs to serve a web application, it will need a self-hosted GitLab runner to manage its deployment.
Installing GitLab runner¶
GitLab runner requires a non-standard Ubuntu repository as an
apt source, before it can be installed:
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash sudo apt-get install gitlab-runner
gitlab-runner package will also create a new user called
gitlab-runner, however, this user may not have a home directory.
$HOME directory will mean that
gitlab-runner can be run as a non-privileged user:
Running pipelines on Docker¶
If you are running pipelines on Docker, there are two more steps to take.
Firstly, locate the
config.toml file for the new runner.
It is likely to be either in
/etc/gitlab-runner/config.toml if you are running
gitlab-runner as root, or
/home/gitlab-runner/.gitlab-runner/config.toml if you are running the service as
Edit the file, and add:
pull_policy = "if-not-present"
This ensures that Docker will use an image held locally on the server, if there is one.
Secondly, add a new file in
docker-prune, with this contents:
#!/bin/sh set -e docker system prune -a --volumes --force
and make it executable:
sudo chmod +x /etc/cron.weekly/docker-prune
This ensures that the server will not run out of disk space, even though
gitlab-runner does not prune its own images.
Register a new runner¶
To register a new runner with GitLab you will need a token.
This can be found on the CI/CD configuration page of your GitLab repository:
Registering the runner is an interactive process, it should look something like this:
$ sudo gitlab-ci-multi-runner register Runtime platform arch=amd64 os=linux pid=29567 revision=de08a4bb version=11.9.1 Running in system-mode. Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/): https://gitlab.com/ Please enter the gitlab-ci token for this runner: TOKEN_FROM_CI_CD_PAGE Please enter the gitlab-ci description for this runner: PROJECT-ENVIRONMENT Please enter the gitlab-ci tags for this runner (comma separated): demo,staging Registering runner... succeeded runner=EygBBkzs Please enter the executor: ssh, virtualbox, docker+machine, docker-ssh+machine, docker, shell, kubernetes, docker-ssh, parallels: shell Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
Check back on your CI/CD configuration page, and you should now see the new runner, with whichever name and tags you have chosen to give it. If you click on the runner ID, you will see a page with some extra options that you might want to consider using, in particular:
- This runner will only run on pipelines triggered on protected branches
- Indicates whether this runner can pick jobs without tags
If your new runner will deploy a public URL, please add it to the company dashboard on uptimerobot for live monitoring, and ensure that alerts go to
email@example.com and to the relevant
-project Slack channel (or
bc-online if your project is internal).
For the Slack alert, you will need to create a new webhook in our Slack app.
If you don't have access to our uptimerobot account, or our Slack app, please ask @snim2 or @a.garcia-dominguez.
If your site has an SSL certificate, please also raise an issue and an MR to add it to our SSL validation script in the cron repository.
Your SSL certificate should also be renewed automatically