GitLab - Installing/Updating a GitLab Runner Container

GitLab runners are agents used to run CD/CD jobs.

They can be shared between all projects or be specific to a single project.

When you self-host GitLab, there are no runners available. Runner or Runners have to be deployed over your infrastructure. This article will guide us through the deployment of a GitLab runner to run our jobs.

1) Pre-Requisites

For compatibility reasons, the runner version should match the GitLab version. Older runners MAY work with newer GitLab versions. However, sometimes minor version updates can introduce new features and break your GitLab Runner and GitLab integration.

Export the GitLab Runner home folder as an enviroment variable.

export GITLAB_RUNNER_HOME=/root/docker-projects/vlan.65-gitlab-runner

2) Docker Compose File

Create the below docker compose file.

version: "3.8"

services:
  gitlab-runner:
    container_name: gitlab-runner
    image: 'gitlab/gitlab-runner:latest'
    restart: always
    hostname: 'git-runner'
    dns:
      - 192.168.65.1
    networks:
            macvlan65:
                  ipv4_address: 192.168.65.11
    ports:
      # Prometheus metrics HTTP server
      - '443:443'
      # Server Session - Enable Interactive web terminal.
      - '8093:8093'
    volumes:
      # Docker Machine executor
      - '$GITLAB_RUNNER_HOME/docker-machine-config:/root/.docker/machine'
      # Self-signed GitLab SSL Cert.
      - '$GITLAB_RUNNER_HOME/gitlab-cert:/etc/gitlab-runner/certs'
      - '$GITLAB_RUNNER_HOME/config:/etc/gitlab-runner'
      - '/var/run/docker.sock:/var/run/docker.sock'
    logging: 
      options:
        tag: "{{.ImageName}}/{{.Name}}/{{.ID}}"
      driver: journald
networks:
  macvlan65:
          external: true

It is needless to say that you need to change the volumes and IP addresses to reflect your infrastructure and bring the container up.

3) GitLab Self-signed certificates

I had some trouble to figure out how to deal with the runner registration failing because of issues with the self signed certificate. The message returned was `Registration Failed: x509: certificate is not valid for any names ...".

It was happening because when I generated my GitLab self signed certs there was no subjectAltName defined. You can check the step 6 of my GitLab tutorial for further information on how the issue with the certificate was fixed.

Copy your GitLab instance self-signed certificate to system folder mapped in the docker-compose file.

gitlab-cert/
└── git.infoitech.co.uk.crt

This solution is listed in the GitLab Documentaion.

UPDATE

After running GitLab with self-signed certificates and changing to Let's Encrypt. GitLab Runner started to fail and the GitLab fullchain Let's Encrypt certificate had to be upload to the folder above.

fatal: unable to access 'https://git.infoitech.co.uk/infoitech/infrastructure/tucana/hv2/proxmox/terraform.git/': SSL certificate problem: unable to get local issuer certificate

4) GitLab Runner Config

Create the config file for the runner and change the below to reflect your needs.

listen_address = "[::]:443"
log_level = "info"
log_format = "text"

[session_server]
  listen_address = "[::]:8093" #  listen on all available interfaces on port 8093
  session_timeout = 1800

If you update the config. The container needs to be restarted. docker container restart gitlab-runner

Bring the container up and inspect its logs to confirm it has no errors.

docker-compose up -d

docker container logs gitlab-runner

Runtime platform                                    arch=amd64 os=linux pid=7 revision=bbcb5aba version=15.3.0
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
Running in system-mode.                            
                                                   
time="2022-08-31T13:43:57Z" level=info msg="Configuration loaded" builds=0
time="2022-08-31T13:43:57Z" level=info msg="Metrics server listening" address="[::]:443" builds=0
time="2022-08-31T13:43:58Z" level=info msg="Session server listening" address="[::]:8093" builds=0

5) Register the Runner

We need to register the recently created runner within our GitLab self-hosted instance.

• Shared Runner

Navigate to Overview > Runners as a GitLab Admin to obtain a registration token.

After obtaining the registration token, we will use the steps described in the GitLab runner documetation to register our runner. The suggested method launches a short-lives gitlab-runner container to register the container created above.

docker run --rm -it -v $GITLAB_RUNNER_HOME/config:/etc/gitlab-runner -v $GITLAB_RUNNER_HOME/gitlab-cert:/etc/gitlab-runner/certs gitlab/gitlab-runner:latest register

Runtime platform                                    arch=amd64 os=linux pid=7 revision=bbcb5aba version=15.3.0
Running in system-mode.                            
                                                   
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://git.infoitech.co.uk
Enter the registration token:
XXXXXXXXXXXXXXXX_TOKEN
Enter a description for the runner:
[30eaf5dc9dba]: gitlab-runner-docker
Enter tags for the runner (comma-separated):
docker
Enter optional maintenance note for the runner:

Registering runner... succeeded                     runner=s_D_syuo
Enter an executor: docker-ssh, parallels, ssh, virtualbox, docker-ssh+machine, custom, shell, docker+machine, kubernetes, docker:
docker
Enter the default Docker image (for example, ruby:2.7):
ubuntu:latest
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
 
Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

• Group Runner

Navigate to the group you want the runner to be registered with. And go to CI/CD > Runners.

Copy the Runner token and use the same docker command used above for the shared runner.

6) Enable Untagged Jobs

By default runners will only run tagged jobs. The GitLab documentation suggests, as best practices, to set at least one tag to the Runner and allow it to run untagged jobs.

As an Admin, navigate to Admin Area > Overview > Runners and click on the runner pencil. Mark the Run untagged jobs and save the changes.

Also, tick protected to limit the runner to run only for protected branches.

7) Updating the Container

To update the container we need to set the below environment variable:

export GITLAB_RUNNER_HOME=/root/docker-projects/vlan.65-gitlab-runner

Let's download the latest image.

docker-compose pull

We will stop the outdated container.

docker container stop gitlab-runner

And finally update it and start.

docker-compose up --no-start
docker container start gitlab-runner

Conclusion

We now have a runner registered with our self-hosted GitLab instance to run CI/CD pipelines.