Skip to content

GitLab Runner Integration

This document outlines the steps needed to create a Docker container named gitlab-runner which will contain a single runner that will be responsible for the execution of Digital Twins. There are two installation scenarios:

  1. Localhost Installation - You are using the integrated runner locally with a GitLab instance hosted at https://localhost/gitlab.
  2. Server Installation - You are using the integrated runner with a GitLab instance hosted on a production server. This server may be a remote server and not necessarily your own, and may have TLS enabled with a self-signed certificate.

Following the steps below sets up the integrated runner which can be used to execute digital twins from the Digital Twins Preview Page.

Prerequisites

A GitLab Runner picks up CI/CD jobs by communicating with a GitLab instance. For an explanation of how to set up a GitLab instance that integrates with a DTaaS application, refer to our GitLab instance document and our GitLab integration guide.

The rest of this document assumes you have a running DTaaS application with a GitLab instance running.

Runner Scopes

A GitLab Runner can be configured for three different scopes:

Runner Scope Description
Instance Runner Available to all groups and projects in a GitLab instance.
Group Runner Available to all projects and subgroups in a group.
Project Runner Associated with one specific project.

We suggest creating instance runners as they are the most straightforward, but any type will work. More about these three types can be found on the official GitLab documentation page.

Obtaining A Registration Token

First, we will obtain the token necessary to register the runner for the GitLab instance. Open your GitLab instance (remote or local) and depending on your choice of runner scope, follow the steps given below:

Runner Scope Steps
Instance Runner 1. On the Admin dashboard, navigate to CI/CD > Runners.
2. Select New instance runner.
Group Runner 1. On the DTaaS group page, navigate to Settings > CI/CD > Runners.
2. Ensure the Enable shared runners for this group option is enabled.
3. On the DTaaS group page, navigate to Build > Runners.
4. Select New group runner.
Project Runner 1. On the DTaaS group page, select the project named after your GitLab username.
2. Navigate to Settings > CI/CD > Runners.
3. Select New project runner.

For any scope you have chosen, you will be directed to a page to create a runner:

  1. Under Platform, select the Linux operating system.
  2. Under Tags, add a linux tag.
  3. Select Create runner.

You should then see the following screen:

Runner Registration Screen

Be sure to save the generated runner authentication token.

Configuring the Runner

Depending on your installation scenario, the runner setup reads certain configurations settings:

  1. Localhost Installation - uses deploy/docker/.env.local
  2. Server Installation - uses deploy/docker/.env.server

These files are integral to running the DTaaS application, so it will be assumed that you have already configured these.

We need to register the runner with the GitLab instance so that they may communicate with each other. deploy/services/runner/runner-config.toml has the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[[runners]]
  name = "dtaas-runner-1"
  url = "https://foo.com/gitlab/" # Edit this
  token = "xxx" # Edit this
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "ruby:2.7"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    volumes = ["/cache"]
    network_mode = "host" # Disable this in secure contexts
  1. Set the url variable to the URL of your GitLab instance.
  2. Set the token variable to the runner registration token you obtained earlier.
  3. If you are following the server installation scenario, remove the line network_mode = "host".

A list of advanced configuration options is provided on the GitLab documentation page.

Start the GitLab Runner

You may use the following commands to start and stop the gitlab-runner container respectively, depending on your installation scenario:

  1. Go to the DTaaS home directory (DTaaS_DIR) and execute one of the following commands.

  2. Localhost Installation

    1
2
    docker compose -f deploy/services/runner/compose.runner.local.yml --env-file deploy/docker/.env.local up -d
docker compose -f deploy/services/runner/compose.runner.local.yml --env-file deploy/docker/.env.local down

  3. Server Installation

    1
2
    docker compose -f deploy/services/runner/compose.runner.server.yml --env-file deploy/docker/.env.server up -d
docker compose -f deploy/services/runner/compose.runner.server.yml --env-file deploy/docker/.env.server down

Once the container starts, the runner within it will run automatically. You can tell if the runner is up and running by navigating to the page where you created the runner. For example, an Instance Runner would look like this:

Status indicator under Admin Area > Runners

You will now have a GitLab runner ready to accept jobs for the GitLab instance.

Pipeline Trigger Token

The Digital Twins Preview Page uses the GitLab API which requires a Pipeline Trigger Token. Go to your project in the DTaaS group and navigate to Settings > CI/CD > Pipeline trigger tokens. Add a new token with any description of your choice.

Creating a Pipeline Trigger Token

You can now use the Digital Twins Preview Page to manage and execute your digital twins.