GitLab CI

Pipeline Configuration File

GitLab CI/CD build for a repository are controlled placing a file named .gitlab_ci.yml in the root folder of the repository. The expected content of the file is specified on GitLab's gitlab_ci.yml Documentation page.

GitLab Runner

Installing

Follow the instructions on this GitLab documentation page, summarized below, where you set up a user account for GitLab Runner and make it launch automatically when your system starts.

sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

You can check the status of the service by typing

sudo gitlab-runner status

Using with Docker

If GitLab Runner is to build your software inside of Docker containers, it needs to able to issue Docker commands. Therefore, make sure Docker is installed and the user gitlab-runner is a member of the docker group:

sudo usermod -aG docker gitlab-runner

which, in virtualized Linux environments, may require a reboot to take effect.

The integration of GitLab Runner with Docker goes deeper than just instantiating a container: Before launching the build scripts from .gitlab_ci.yml, GitLab Runner will clone the repository into a build folder inside the container! The default path is /build/ followed by the project path on the GitLab server. The build scripts simply leave it to GitLab Runner to provide them with the correct commit from the correct branch.

Registering the Runner

After GitLab Runner is installed, you will need to register the runner with the GitLab code repository. Typing

sudo gitlab-runner register

launches the interactive registration, which will prompt you for each of the configuration parameters. You can also supply some or all of the parameters directly in the command:

sudo gitlab-runner register \
  --url "https://" \
  --registration-token <secret token> \
  --description "docker-swift:5.4" \
  --executor "docker" \
  --docker-image swift:5.4

where <secret token> is the token obtained from GitLab project settings → CI/CD → Runners → Specific Runners.

Registration finishes by generating the /etc/gitlab-runner/config.toml file similar to this:

concurrent = 1 
check_interval = 0 

[session_server]
  session_timeout = 1800

[[runners]]
  name = "ubuntu-at-home"
  url = "https://gitlab.com/"
  token = <secret token>
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "keytree"
    privileged = false
    disable_entrypoint_overwrite = false
    pull_policy = "never"
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0 

after which, the gitlab-runner service will notice that the configuration file has changed and applies the new configuration.

Note that the pull_policy option was explicitly set to "never" instead of going with the default "always". This prevents GitLab Runner from searching for the specified Docker image on Docker Hub and directs the query to the local docker engine!