Skip to content

GitLab Runner

GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline. A runner is a process that can run on any computer and process pending jobs. A distinction must be made between “shared”, “group” and "project" runners. A specific runner only serves for certain projects, a group runner is dedicated to process only jobs associated to projects in a group, and shared runners are available to all groups and projects in a GitLab instance. You can find available runner type in the project settings Settings -> CI/CD -> Runners.

PLEASE NOTE❗: the offered runners are currently in Alpha phase. We are testing the technology behind them and we are going to improve the offer step by step. Our priority is to affect existing users as least as possible, but because we will make changes it is highly possible that some pipeline settings or setups have to be changed over time.

Runner types

GitLab at KIT provides project/group and instance (shared) runners.

The project and group runner in KIT only serves jobs for a group or a project. On the other hand the instance runners are shared with everyone. In both cases a individual temporary container is created for each job.

In case of the project runner, the runner can be used for all projects and subgroups inside of that group.

How to request a gitlab-runner for our group or project?

To use a gitlab-runner, you must fill out a short form. First, visit IT-Surpport Ticket page and go to customer login.

alt text

If you open a new ticket, you will find a request form in the text template with the title "GitLab at KIT: Request for the provision of GitLab Runner (en)"

You can fill out your profile and request in this form. Here is an example:

  • Name: Your Name
  • E-mail: your.name@kit.edu

  • GitLab Runner will be placed for following project/group (URL): [https://gitlab.kit.edu/gruppe/projekt]

  • (Optional) Do you have to parallelise your jobs/tasks with several Runners? How many runners are required in the CI/CD pipeline? (Default : 1 Runner): [x runner]

  • (Optional) How long do you need GitLab Runners in your personal or group project (max 6 months): [1 week/3 months/6 months]

The runner will be provided to you as soon as the provisioining and assignment process is completed.

Specification of a project/group runner

The GitLab-Runner is installed on a Kubernetes-Tanzu-Cluster in the VMware infrastructure and ready to process jobs/tasks in a container.

There are multiple sizes of runners. For project/group runners the standard size is used (on demand the size or number of runners can be adjusted for project runners). For instance runners all sizes are used. The sizes are following:

  • kgr1-instance-mini:
    • Tag: kgr1-instance-mini
    • Parallel: 20
    • Cores: 0.5-0.5
    • Memory: 1.6-2 GiB
    • Disk: 11-13 GiB
  • kgr1-instance-standard:
    • Tag: kgr1-instance-standard
    • Parallel: 20
    • Cores: 1-1
    • Memory: 2.8-3.8 GiB
    • Disk: 16-26 GiB
  • kgr1-instance-extraordinary:
    • Tag: kgr1-instance-extraordinary
    • Parallel: 1
    • Cores: 4-6
    • Memory: 44-45 GiB
    • Disk: 103-112 GiB

Timeout for all runners is 1 hour.

NOTE 🗒: The sizes have each individual sizes of help and service containers. If you are not using them specifically you can ignore the following specification * mini service container: 0.2-0.5 cores, 0.5-1 GB * mini helper container: 0.1-0.3 cores, 0.5-1 GB * standard service container: 0.5-1 cores, 1-2 GB * standard helper container: 0.2-0.5 cores, 0.5-1 GB * extraordinary service container: 0.5-1 cores, 2-8 GB * extraordinary helper container: 0.5-1 cores, 1-2 GB

How to use the runner

NOTE 🗒: This is a brief guide on how to use our runners. To get information on how to use GitLab Runner please read the official documentation about runners.

  1. Enable the runner for your project
    • You can do this inside of projects settings->CI/CD->runners
  2. Create a CI/CD configuration with a name .gitlab-ci.yml file and commit changes
  3. The runner should pick up the job and go with the steps of the runner

Choosing Linux Distribution (Optional)

Use image variable to specify the runner. If you don't specify it, the runner will use Ubuntu.

You can use following or your own images:

  • ubuntu:<version>"
    • default - ubuntu:latest if not specified otherwise
    • for latest version use ubuntu:latest
  • alpine:<version>
    • lightweight linux image
    • recommended if you want to keep more resources for your builds, scripts, etc.
    • for latest version use alpine:latest
  • centos:<version>
    • for latest version use centos:latest
  • debian:<version>
    • for latest version use debian:latest
  • fedora:<version>
    • for latest version use fedora:latest
  • archlinux:<version>
    • for latest version use archlinux:latest
  • registry.suse.com/suse/sles12sp5:<version>
    • for latest version use registry.suse.com/suse/sles12sp5:latest
  • opensuse/leap:<version>
    • for latest version use opensuse/leap:latest
  • kalilinux/kali-rolling:<version>
    • for latest version use kalilinux/kali-rolling:latest
  • rockylinux:<version>
    • for example use rockylinux:9.3-minimal (newest minimal as of june 2024)
  • amazonlinux:<version>
    • for latest version use amazonlinux:latest *oraclelinux:<version>
    • for example use oraclelinux:9 (newest as of june 2024)
  • clearlinux:<version>
    • for latest version use clearlinux:latest
  • gitlab/gitlab-runner:latest
  • gitlab/gitlab-runner:ubuntu
    • the version might be older, if not acceptable use ubuntu:latest
  • gitlab/gitlab-runner:alpine
    • if you want to use specific version use alpine:<version>
  • gitlab/gitlab-runner:ubi-fips
    • Universal Base Image that is configured to comply with FIPS standards (Red hat based)

NOTE🗒: Not every version might be available, check before or use the specified version or latest if available.

CI/CD configuration files examples

Example of .gitlab-ci.yml - hello world

hello_world:
  # using tagged runner with tag "eager-blackbear-0"
  tags:
    - "eager-blackbear-0"

  # specifying stage 
  # (most common stage and order is build->test->deploy)
  stage: build

  # if image not specified then the default is used
  # default: image: "gitlab/gitlab-runner:ubuntu"

  # specifying the commands to be run by the runner
  script:
    - echo "Hello world"

Example of .gitlab-ci.yml - extension

build_the_script:
  tags:
    - "eager-blackbear-0"
  stage: build
  image: "gitlab/gitlab-runner:ubuntu"

  script:
    - echo "print(42)" > get_answer.py 

  # using artifact to pass script to next stage 
  artifacts:
    paths:
      - get_answer.py


test_the_script:
  tags:
    - "eager-blackbear-0"
  stage: test
  image: "gitlab/gitlab-runner:ubuntu"

  script:
    - apt update
    - apt install python3 -y
    - if [ "$(python3 get_answer.py)" == "42" ]; then echo 'Answer is correct'; else echo 'Answer is NOT correct'; fi

Runner with a tag and variables

A tag can be used to control which jobs can be executed on which runners and for which sub-group or specific projects. If tags have been assigned to a job, it will only run on a runner with the appropriate tags.

In the .gitlab-ci.yml file, use CI/CD variables with tags for dynamic runner selection: 

    variables:
      KIT_KUBERNETES_RUNNER: kit-öjwenadnh64$s82gowß3urhnßü1nvwß1nvsa

      job:
        tags:
          - docker
          - $KIT_KUBERNETES_RUNNER
        script:
          - echo "Hello runner selector feature"

Tag of KIT runner

Specify the tag of the runner in tags sequence if you need to specify the runner to be used (more on that in section below): 

tags:
  - "eager-blackbear-0"

Variables

Sensitive variables such as tokens or passwords should be stored in the settings in the user interface, preferably not in the .gitlab-ci.yml file. You can define CI/CD variables in the UI Settings -> CI/CD -> Variables.

alt text

Security

When setting up your runners, you should pay attention to the security and protection of confidential data. Any user who has the access rights to the project can also execute arbitrary but unverified commands. When you are setting up your runner, you must ensure that no confidential information is accessible to ungranted user. Particularly for using shared runners, it should be noticed that the runner's private authentication token could be readable and the runner could be imitated by another machine.

Rate-Limit

To ensure a continuous service for all users, projects and groups, each project can start a maximum of 5 pipelines per minute. If this is not sufficient in your case, please write us a ticket with a brief explanation why more simultaneous pipelines need to be active in your project.

Specific needs

If you have specific needs for a runner with a good reason you can contact us with the ticket and write your request.