Step 2: Activate Runner

Without at least one Runner, nothing works in GitLab. A Runner is something like a remote command receiver running on a system waiting for instructions from the GitLab CI suite. It covers the entire CI process, including building the image and carrying out the defined tests. If you haven't used GitLab CI yet, you usually won't have an active Runner, so creating such a Runner is the next step on the way to automating Docker containers.

The Runner can reside on the same host as GitLab itself, but it is more elegant if the Runner has its own system and does not have to share its resources with other services. Additionally, the Docker Community Edition must be installed on the Runner host for the Docker command to work. You need to pick up an authentication token for the new Runner as the first step: In GitLab, click Overview | Runners on the admin page, where you will find a corresponding token (Figure 1).

Figure 1: In the GitLab Admin Area, you can pick up a token for new Runners and manage existing Runners.

The GitLab developers provide a package installation script that can be found online for Debian-based [5] and RPM-based [6] systems (except openSUSE). If you are brave, download the script and execute it immediately with:

curl -L | sudo bash

If you want to look into the script first, download it and execute it manually as root. At the end of the process, the gitlab-runner package is installed.

Finally, it is time to register the Runner in GitLab. To start the process, enter:

sudo gitlab-runner register

The program wizard first asks for the GitLab URL and then for the token from the previous step. Enter the host name accordingly and answer the prompt for possible tags by typing Docker and the prompt related to running Untagged jobs with true .

Your response to the question about pinning to the current project needs to be false . Finally, as the executor, enter shell – a more complicated setup would connect the GitLab Runner directly to Docker via the dedicated executor, but it is not necessary in this basic example.

At the end of the process, the new Runner appears in GitLab: A new entry can now be found where you previously retrieved the token. By the way, various parameters of the Runner can be changed here retroactively at any time. If something goes wrong during the initial setup of the Runner, the wrong configuration is not set in stone.

Step 3: Activate GitLab CI for Project

The final step in GitLab preparation is to activate the CI framework for the sample project. To do this, first create a new project in GitLab and then navigate to its settings. There, click Settings | CI/CD and then Expand next to General Pipeline Settings to open the most important configuration settings. Set the Git strategy for pipelines value to git clone .

Next, click Settings and right-click Permissions . Pressing Expand makes the project settings visible; here, you need to set the Container registry value to Enabled (Figure 2) to enable the GitLab CI framework for the sample project. However, you still need a trigger to launch any CI automation – which you will address in the last step.

Figure 2: After enabling the GitLab Docker registry, use it for specific projects within GitLab.

Step 4: Define CI Pipelines

GitLab expects the .gitlab-ci.yml CI project configuration file in the root directory of the project. The content and principle of the desired YAML file is similar to that of a makefile: Define the parts (stages) of the CI process and stipulate which jobs belong to each stage. Because GitLab simply calls a shell externally to perform the individual steps in the stages, the individual stages can be defined in the form of shell scripts, which you can access in .gitlab-ci.yml and then simply reference. This arrangement helps keep the YAML file itself understandable.

Basically, the names of the individual jobs can be chosen freely, but the YAML hierarchy of GitLab CI has a few reserved keywords. Under stages, for example, GitLab expects a list of the CI stages of the project. With before_script and after_script, GitLab accepts commands defined before and after individual jobs are run. Variables can be set with the variables directive. See the GitLab documentation [7] for details.

In the example, .gitlab-ci.yml has the following stages: pre_cleanup, build, test, upload, and post_cleanup, which are also defined in stages. The jobs are then defined:

<name>:
  script: <command>
  stage: <section>
  tags:
    - dock

The name of a job can be, but does not have to be, identical to the section of the build process to which the job belongs. However, making it match contributes considerably to clarity. The complete build job could look like this:

build:
  script: "bash -x build.sh"
  stage: build
  tags:
    - Docker

This entry in .gitlab-ci.yml causes GitLab CI to call the bash -x build.sh command each time it processes the build section in the CI process. The actual commands needed to create the image for Docker (i.e., Docker build) are then in build.sh, which gives this solution elegance and helps avoid a mess in .gitlab-ci.yml. By the way, the environment of a job can be defined dynamically, which enables further standardization.

For example, it makes sense to create a shell script named .gitlab-ci.config that exports the IMAGE, IMAGE_NAME, and VERSION environment variables to the shell environment. If you then get these environment variables into the shell by using ./.gitlab-ci.config in the first stage of the CI process, all further commands of this job have access to them. Also important is that a script directive in a job description can call multiple commands if YAML notation is used.

Similar to the build example, you can add additional jobs for the other stages in .gitlab-ci.yml; each section gets its own shell script (e.g., pre_cleanup.sh, test.sh, upload.sh, and post_cleanup.sh). The final interesting question against this backdrop is what the content of those shell scripts should be.