How to SetUp GitLab Runner with Docker Executor

Introduction

In DevOps workflows, CI/CD pipelines automate the process of building, testing and deploying applications. A key component that executes the pipeline jobs is GitLab Runner, and an efficient GitLab Runner Docker setup ensures reliable and scalable execution environments.

What is GitLab Runner?

GitLab Runner is a machine or service that executes the jobs defined in a CI/CD pipeline. When a pipeline runs, GitLab sends the job instructions to a Runner. The Runner then executes the commands defined in the pipeline stages.

Think of it like this:

• GitLab CI/CD pipeline defines what to do
• GitLab Runner executes those tasks

It works similarly to how we run Linux or PowerShell commands on our own laptop. The Runner simply executes those commands on a machine.

Key responsibilities of GitLab Runner:

• Executes CI/CD pipeline jobs
• Runs scripts defined in .gitlab-ci.yml
• Reports job results back to GitLab
• Supports multiple execution environments

What is Docker Executor?

The Docker Executor is a runner configuration that allows CI/CD jobs to run inside Docker containers.

Instead of executing jobs directly on the host machine, each job runs inside a separate Docker container.

Benefits of Docker Executor

1. Consistent Environment

2. Dependency Isolation

3. Security

4. Scalability

Prerequisites

Before installing GitLab Runner with Docker executor, ensure the following:

• Linux system
• Docker installed
• Access to a GitLab project

Step-by-Step Installation Guide

Step 1: Install Docker

First, install Docker on the system where the GitLab Runner will run. Follow the official Docker documentation for installation.

Step 2: Install GitLab Runner

Docker is required only when you plan to use the Docker Executor. To install GitLab Runner on Ubuntu systems, follow these steps.

Add the GitLab repository

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

Install GitLab Runner

sudo apt-get install gitlab-runner

Once installed, the Runner service will be available on your system.

Register the Runner in GitLab

After installation, the Runner must be registered with a GitLab project.

Step 3: Run the Register Command

sudo gitlab-runner register

You will then be prompted to enter several details.

Step 4: Enter GitLab URL

https://gitlab.com

If using a self-hosted GitLab instance, provide its URL.

Step 5: Enter Registration Token

You can find the Runner Registration Token in your GitLab project:

Project → Settings → CI/CD → Runners → Project Runners

Copy and paste the token when prompted.

Step 6: Enter Runner Description

Provide a description to identify the runner.

Example: docker-runner

Step 7: Enter Job Tags

Tags help GitLab decide which runner should execute a job.

Example: gitlab, runner

These tags must match the tags defined in the .gitlab-ci.yml pipeline.

Step 8: Choose Executor

When prompted for executor type, enter:

docker

This configures the runner to use Docker containers for executing CI/CD jobs.

Runner Setup Complete

Once the registration is completed:

• The runner will appear in your GitLab project under Project Runners
• It is now ready to execute pipeline jobs
• Any pipeline job with matching tags will run on this runner

Conclusion

GitLab Runner plays a crucial role in executing CI/CD pipelines. Using the Docker Executor provides a reliable, isolated, and scalable environment for running jobs. By completing a proper GitLab Runner Docker setup, you can streamline automation and improve consistency across your development workflows.

By installing Docker, setting up GitLab Runner, and registering it with your project, you can easily automate builds and deployments in GitLab. This approach is widely used in modern DevOps practices because it ensures consistent execution environments and simplifies dependency management.

If you’re looking to implement or optimize this setup without complexity, our expert DevOps Support Services are here to help. From configuring GitLab Runner with Docker to building scalable CI/CD pipelines, we ensure a seamless and efficient deployment process. Get in touch with our team today and take your DevOps automation to the next level