Log In

Installing and Using GitLab Runner

Installing and Using GitLab Runner
Git GitLab CI/CD
27.05.2024
Reading time: 5 min
Hostman Team
Technical writer

GitLab Runner is a web application (agent) designed to launch and automatically run CI/CD processes in GitLab. GitLab Runner runs tasks from the .gitlab-ci.yml file, which is located in the root directory of your project.

Runner can be installed either on the same server with GitLab or separately. The main thing is that there is network communication between GitLab Runner and the GitLab server. You can install Gitlab Runner on operating systems such as Linux, Windows, macOS, and it also supports running in a Docker container.

In this article, we will install GitLab Runner in Docker and run a test project.

Prerequisites

To install GitLab Runner, you will need:

  • A cloud server or a virtual machine running a Linux OS. You can use any Linux distribution compatible with Docker.

  • Docker installed. 

  • An account on gitlab.com, as well as a pre-prepared project.

You can install Docker manually (we have a step-by-step guide for Ubuntu) or automatically from Marketplace, when creating a new Hostman server.

Image1

Installing GitLab Runner using Docker

First, connect to the server where Docker is installed.

Create a Docker volume in which we will store the configuration.

A Docker volume is a file system for persistent storage of information. Data in a volume is stored separately from the container. The volume and the data will remain if you restart, stop, or delete the container. 

The command to create a volume named runner1 is:

docker volume create runner1

Next, launch the container with the gitlab-runner image:

docker run -d --name gitlab-runner1 --restart always \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v runner1:/etc/gitlab-runner\
     gitlab/gitlab-runner:latest

Check the status of the container and make sure that it is running (Up):

docker ps

Image10

This completes the installation of GitLab Runner. The next step is Runner registration.

Registering GitLab Runner

Once Runner has been installed, it must be registered. Without registration, Runner will not be able to complete tasks.

  1. Launch the gitlab-runner container and execute the register command:
docker run --rm -it -v runner1:/etc/gitlab-runner gitlab/gitlab-runner:latest register
  1. You will be prompted to enter the URL of the GitLab server:

Image14

If you are using self hosted GitLab installed on a separate server, use the address of your GitLab instance. For example, if your project is located at https://gitlab.test1.com/projects/testproject, then the URL will be https://gitlab.test1.com.

If your projects are stored on GitLab.com, then the URL is https://gitlab.com.

  1. Next, you will need to enter the registration token.

To get the token, go to the GitLab web interface, select the project, select the Settings section on the left, then CI/CD:

Image4

Find the Runners menu, expand the section. You will find the token in the Action menu (three dots):

Image9

  1. Next, you'll be prompted to enter a description for this Runner. You can skip it not writing anything:

Image3

  1. Now you need to set the tags. Tags are labels designed to determine which runner will be used when running tasks. You can enter one or several tags separating them by commas:

Image11

  1. When entering a maintenance note, you can add information for other developers, containing, for example, technical information about the server. You can also skip this step. 

Image2

  1. Select an executor, i.e. the environment for launching the pipeline. We will choose docker. In this case, the pipeline will be launched in Docker containers, and upon completion, the containers will be deleted.

Image5

  1. At the last step, select the Docker image to use in the container where the pipeline will be launched. As an example, let's choose the python 3.10-slim image:

Image17

After you are done registering the Runner, it will be displayed in the project settings, in the Runners section:

Image7

Using GitLab Runner when starting a pipeline

In order to use Runner to run a pipeline, you need to create a file called .gitlab-ci.yml. You can create a file directly in the root directory of the project or in the GitLab web interface:

  1. On the project main page click Set up CI/CD (this button is only visible before you set up CI/CD for the first time):

Image1 (1)

  1. Click Configure pipeline:

Image8

When you first set up a pipeline, GitLab provides the basic pipeline syntax. In our example, we use a Python project, namely a script to test the speed of an Internet connection. If the script executes successfully, the output should display information about incoming and outgoing connections:

Your Download speed is 95.8 Mbit/s
Your Upload speed is 110.1 Mbit/s

The pipeline syntax will look like this:

image: python:3.10-slim
default:
   tags:
     - test1
before_script:
     - pip3 install -r requirements.txt
run:
   script:
     - python3 check_internet_speed.py

To assign a previously created Runner to this project, you need to add:

default:
   tags:
     - test1

Where test1 is the tag of the Runner we created. With this tag, the pipeline will be executed on the Runner that is assigned the test1 tag. Save the changes to the file (make a commit) and launch the pipeline. If you look at the job execution process, you can see at the very beginning of the output that the gitlab runner is used:

Image13

The full output of the entire pipeline is shown in the screenshot below:

Image15

Conclusion

In this tutorial, we have installed and configured GitLab Runner, assigned it to a project, and launched the pipeline.

Share