DEV Community

Mario García
Mario García

Posted on • Edited on

Configure your own GitLab Runner

#tutorial #gitlab #linux

When you create a new account on gitlab.com, you would have to provide a valid credit/debit card for being able to use free minutes of GitLab Runner.

From the Frequently Asked Questions in the Pricing page, if you choose to use GitLab.com SaaS shared runners, a valid credit/debit card is required as there has been a massive uptick in abuse of free compute minutes available on GitLab.com SaaS to mine cryptocurrencies - which creates intermittent performance issues for GitLab.com SaaS users.

For those who are privacy concerned, you can install GitLab Runner on an infrastructure you own or manage. It can be installed:

Install GitLab Runner on Linux

You can install GitLab Runner on Linux using the GitLab repository.

On Debian and derivatives, you should add the official GitLab repository by running the following command:



curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
Enter fullscreen mode Exit fullscreen mode

Then, install the latest version of GitLab Runner:



sudo apt install gitlab-runner
Enter fullscreen mode Exit fullscreen mode

To install a specific version:



apt-cache madison gitlab-runner
sudo apt-get install gitlab-runner=15.11.0
Enter fullscreen mode Exit fullscreen mode

Replacing 15.11.0 with the required version.

And finally, register the runner.

For instructions to install GitLab Runner on other distros, check the documentation.

Create a Shared Runner

There are two ways for creating a shared runner:

  • With a runner authentication token
  • With a registration token

Using a runner registration token was deprecated in GitLab 15.6 and will be removed in GitLab 18.0. Instead, a runner authentication token will be used. More information in the documentation.

The GitLab Runner can be created directly from the UI following the next steps:

  1. Go to Settings → CI/CD, in your project
  2. Expand the Runners section
  3. Select New project runner
  4. Select the operating system where you installed GitLab Runner
  5. Assign tags to the jobs in your CI/CD pipeline that the runner can run, otherwise mark Run unstagged jobs
  6. Add a runner description (optional)
  7. The Configuration section is also optional
  8. Select Create runner

Register the Runner

After creating the runner, you will get instructions for registering the runner, including the token required.

Run the following command:



sudo gitlab-runner register  --url https://gitlab.com  --token glrt-JQcTiXyMdgsi5K5BemS6
Enter fullscreen mode Exit fullscreen mode

glrt-JQcTiXyMdgsi5K5BemS6 is the authentication token, generated after creating the runner.

It will prompt you to type the GitLab instance URL (e.g. https://gitlab.com).

Then, enter a name for the runner, stored in the local config.toml file.

Select an executor. You can use Docker for a clean build environment.

If you choose Docker, you should enter the default Docker image to use (e.g. ruby:2.7). Default image to use when not defined in your .gitlab-ci.yml file.

Once the runner is registered, you can verify if it's available to pick up jobs:



sudo gitlab-runner run
Enter fullscreen mode Exit fullscreen mode

And you're ready to go. You have a GitLab Runner up and running that can be used with your CI/CD pipelines.

Deprecated Tutorial
When configuring a new GitLab account on GitLab.com you would get access to a 30-day GitLab Ultimate trial and would be required to validate your account with a credit card for using free minutes of GitLab Runner.

For those who are privacy concerned, you can install GitLab Runner on an infrastructure you own or manage. It can be installed:

Run GitLab Runner in a container

Before installing GitLab Runner, make sure Docker is up and running on your system. On GNU/Linux follow the instructions in the documentation or go directly to the section that covers the instructions for your distro:

Don't forget to follow post-installation steps.

Install the Docker image and start the container

For installing the Docker image, create a Docker volume:



docker volume create gitlab-runner-config
Enter fullscreen mode Exit fullscreen mode

Start the GitLab Runner container:



docker run -d --name gitlab-runner --restart always \
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v gitlab-runner-config:/etc/gitlab-runner \
 gitlab/gitlab-runner:latest
Enter fullscreen mode Exit fullscreen mode

Register your runner

Before using your recently installed GitLab Runner, you have to register it.

Go to the settings of a GitLab project that you want to use GitLab Runner for and obtain the registration token. In your GitLab repository, go to Settings --> CI/CD and expand the Runners section. From the Specific runners section, copy the registration token. Don't forget to disable Shared runners.

Now from the terminal, run the following command:



docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
Enter fullscreen mode Exit fullscreen mode

It will ask you for the following information:

  • Enter the GitLab instance URL: https://gitlab.com/
  • Enter the registration token: The one you copied before
  • Enter a description for the runner: What you're planning to use it for
  • Enter tags for the runner: Tags are comma separated and assign manually to jobs in your CI/CD pipelines. You can edit them later
  • Enter optional maintenance note for the runner.
  • Enter an executor: docker
  • Enter the default Docker image: ruby:2.7. Default image to use when not defined in your .gitlab-ci.yml file.

If you don't assign tags to the jobs in your CI/CD pipeline, the GitLab Runner won't start as it is configured by default to pick jobs that have any of the tags specified in the configuration.

For changing this behavior and let the GitLab Runner pick jobs without tags, expand the Runners section from Settings --> CI/CD and click the edit button in the runner you want to modify from the Available specific runners section. Then check the following option: Indicates whether this runner can pick jobs without tags.

By default runners are configured to use them only with a specific project, If you want other projects in your account to use this runner, uncheck the option: When a runner is locked, it cannot be assigned to other projects. In other projects, expand the Runners section from Settings --> CI/CD, go to the Available specific runners and click on Enable for this project to choose the runner you want use from the available ones.

Now you're ready to use GitLab CI and configure your CI/CD pipelines using your own GitLab Runner.


Support me on Buy Me A Coffee

Top comments (0)

Read next

mshsayket profile image

How to Install Bootstrap 5 in Laravel 11 with Vite?

Saddam Hossain -

muash10 profile image

Using Stable Diffusion in AWS Bedrock to Generate Images

Muhammed Ashraf -

furkangozukara profile image

Example Training Images Dataset, Trained Models, Grids and Full Training Configs, json files and more

Furkan Gözükara -

dm8ry profile image

Demonstrating Persistence vs. Non-Persistence in Kubernetes with MongoDB

Dmitry Romanoff -