Setting Up GitLab CI Runners: A Step-by-Step Guide

Welcome to our guide on installing GitLab CI Runners! If you’re ready to supercharge your CI/CD pipelines with high-performance runners, you’re in the right place. This guide will take you through the process, ensuring your runners are up and running smoothly in no time.

Why Use GitLab CI Runners?

GitLab CI Runners are essential components of your CI/CD workflows. They are lightweight agents that execute your pipeline jobs, whether it’s building, testing, or deploying your code. While GitLab provides shared runners for public projects, self-managed runners offer distinct advantages:

Isolation and Customization: Set up tailored environments for consistent and reproducible builds.
Scalability: Easily scale your infrastructure by adding or removing runners as needed.
Security: Keep control of your CI/CD jobs by hosting runners on your infrastructure.

Self-managed runners are a must-have for teams seeking more control and flexibility in their pipelines.

Prerequisites

Before you begin, ensure you have the following in place:

A GitLab instance (either self-managed or hosted on GitLab.com).
A dedicated machine for the runner.
The GitLab Runner binary installed on the host machine.

How to Set Up GitLab CI Runners

Follow these steps to get your GitLab CI Runner ready:

Step 1: Create the Runner

Navigate to your GitLab repository.
Go to Settings > CI/CD and expand the Runners section.
Click Register a Runner, and assign tags to it (e.g., docker, test-runner) for better job management.

Step 2: Register the Runner

On the host machine, open a terminal with sudo permissions and run the following commands:

Enter your registration URL and token (provided in the GitLab UI).
Execute the command:


Copied!gitlab-runner register
gitlab-runner register

Follow the prompts to configure your runner (e.g., tags, executor type like Docker or Shell).

Step 3: Configure the Runner

Edit the runner’s configuration file (/etc/gitlab-runner/config.toml) to match your project’s needs. For example:


Copied![[runners]]
 name = "My Self-Managed Runner"
 url = "https://gitlab.com/"
 token = "your_registration_token"
 executor = "docker"
 [runners.docker]
   image = "alpine:latest"
   privileged = true
   tls_verify = false
[[runners]]
 name = "My Self-Managed Runner"
 url = "https://gitlab.com/"
 token = "your_registration_token"
 executor = "docker"
 [runners.docker]
   image = "alpine:latest"
   privileged = true
   tls_verify = false

Step 4: Start the Runner

Start your runner using these commands:


Copied!sudo gitlab-runner start
sudo gitlab-runner run
sudo gitlab-runner start
sudo gitlab-runner run

If you make changes to the configuration file, restart the runner with:


Copied!sudo gitlab-runner restart
sudo gitlab-runner restart

Setting Up `.gitlab-ci.yml`

The .gitlab-ci.yml file is the heart of your GitLab CI/CD pipelines. Ensure it’s named exactly .gitlab-ci.yml and contains the correct tags assigned to your runner. Here’s an example:


Copied!stages:
  - build

build-job:
  stage: build
  script:
    - echo "Building the project..."
  tags:
    - test-runner
stages:
  - build

build-job:
  stage: build
  script:
    - echo "Building the project..."
  tags:
    - test-runner

When committed, GitLab will automatically trigger pipelines based on this file.

Looking for a Managed GitLab Runner Solution?

Managing self-hosted GitLab Runners can be challenging—monitoring, scaling, and maintaining them takes time and effort. If you want a hassle-free alternative, check out Cloud Runner.

With Cloud Runner, you get:

Up to 60% faster pipelines with optimized infrastructure.
Automatic scaling to meet your CI/CD demands.
Flat-rate pricing, with no surprise costs.

Skip the headaches of self-hosted runners and let Cloud Runner handle it for you!