[Infrastructure as Code (IaC)] How to Install and Register GitLab Runner and Shell Executor on CentOS

How to Install and Register GitLab Runner and Shell Executor on CentOS

In today’s DevOps landscape, continuous integration and continuous delivery (CI/CD) pipelines are essential for delivering high-quality software. GitLab Runner, a tool used to run jobs in a GitLab CI/CD pipeline, is an integral part of this process. This guide will walk you through installing and registering GitLab Runner on CentOS, ensuring you have a reliable setup for your development workflow.


Before you begin, ensure you have:

  • A CentOS system (version 7 or later)
  • Root or sudo access to the system
  • A GitLab instance and a registration token for the runner

Step 1: Add the Official GitLab Repository

The first step is to add the official GitLab repository to your system. This repository contains the latest version of GitLab Runner and ensures that you get updates directly from GitLab.

Open your terminal and run the following command:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash`

This command downloads and executes a script that adds the GitLab repository to your system.

Step 2: Install GitLab Runner

Once the repository is added, you can install GitLab Runner using the yum package manager. Run the following command:

sudo yum install gitlab-runner

This command installs the GitLab Runner package and its dependencies on your CentOS system.

Step 3: Register GitLab Runner

After installing GitLab Runner, the next step is to register it with your GitLab instance. This process links the runner to your GitLab projects, allowing it to execute CI/CD jobs.

Run the following command to start the registration process:

gitlab-runner register

You will be prompted to enter several pieces of information during the registration process:

  1. GitLab instance URL: Enter the URL of your GitLab instance (e.g., https://gitlab.com/ or your self-hosted GitLab URL).
  2. Registration token: Enter the registration token provided by your GitLab instance.
  3. Description: Provide a description for the runner to help identify it in the GitLab interface.
  4. Tags: Enter tags for the runner, separated by commas. These tags are used to match jobs with runners.
  5. Executor: Choose the executor for the runner. For this guide, we’ll use shell.

An example registration session might look like this:

Runtime platform                                    arch=amd64 os=linux pid=7947 revision=44feccdf version=17.0.0
Running in system-mode.

Enter the GitLab instance URL (for example, https://gitlab.com/):
Enter the registration token:
Enter a description for the runner:
[xxxx]: xxx
Enter tags for the runner (comma-separated):
Enter optional maintenance note for the runner:

Registering runner... succeeded runner=DAM2LCZd
Enter an executor: custom, parallels, docker, docker+machine, kubernetes, instance, shell, ssh, virtualbox, docker-windows, docker-autoscaler:
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

After successful registration, the configuration is saved in /etc/gitlab-runner/config.toml.

Step 4: Start GitLab Runner

Once the runner is registered, you can start it using the following command:

sudo gitlab-runner start

This command starts the GitLab Runner service, allowing it to pick up and execute jobs from your GitLab instance.


By following these steps, you have successfully installed and registered GitLab Runner on your CentOS system. This setup allows you to leverage GitLab’s powerful CI/CD capabilities, automating your build, test, and deployment processes. For more detailed information and advanced configurations, refer to the official GitLab documentation.

Happy building!