Learn GitLab CI/CD - Setting Up & Managing GitLab Runners

#Introduction

In episode 2 you successfully created your first .gitlab-ci.yml and got a pipeline running. But have you ever asked: who actually runs that job? The answer is the GitLab Runner — the unsung hero that picks jobs up from the queue and executes them. This episode dissects runner type classifications, executor types, how to register, and how tags route jobs to the right runner.

This understanding is crucial: in large companies, the runner architecture determines the speed, cost, and security of the entire pipeline. Decisions like "run on a shared runner or a dedicated runner?" and "use a Docker executor or a Kubernetes executor?" are architectural decisions, not just configuration.

#Main Discussion

#GitLab Runner Type Classifications

Runners can be distinguished by the scope of their service:

• Shared Runners — provided by GitLab.com free of charge to all users; on a self-hosted instance, shared runners are configured by admins for the whole instance. Good for starting out without your own infrastructure.
• Group Runners — owned by a single Group/Organization and serve all projects within that group. Ideal for standardizing capacity across projects in one team.
• Specific / Project Runners — dedicated to a single project only. Used for special needs: GPU hardware, security requirements, or environment isolation.

Here's a simple analogy: a shared runner is like public shuttle service, a group runner is like an office shuttle bus serving all divisions, and a specific runner is like a private car serving one office — with specs that can be customized.

#Executor Types on GitLab Runner

The executor determines how the runner executes jobs. The three most popular:

• Shell executor — executes scripts directly on the runner's host OS. Simplest and fastest, but jobs aren't isolated: scripts can touch host files and services. Good for simple machines or host access needs.
• Docker executor — runs jobs inside isolated Docker containers. The most popular because it's clean, consistent, and uses different images per job (via the image keyword). This is the standard for production pipelines.
• Kubernetes executor — dynamically creates a new pod per job in a Kubernetes cluster. Ideal at scale: pods are spawned when a job arrives and deleted when done, so resource utilization is efficient.

By analogy: the shell executor is like cooking directly in the shared kitchen, the docker executor is like cooking in your own clean, portable pot, while the kubernetes executor is like ordering a brand-new chef for every order.

#Installing GitLab Runner

Runners run on machines you control — a laptop, VM, or CI server. Installation on Ubuntu/Debian uses GitLab's official repository:

curl -sS https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get update
sudo apt-get install -y gitlab-runner
gitlab-runner --version

The runner is registered as a system service (gitlab-runner), and all configuration is stored in /etc/gitlab-runner/config.toml.

#Registering a Runner

Every runner must be registered to GitLab with a unique token. The token is taken from Settings → CI/CD → Runners in the project, group, or instance — depending on the runner type you want to create. Example non-interactive registration:

gitlab-runner register \
  --url https://gitlab.com/ \
  --token glrt-XXXXXXXXXXXX \
  --executor docker \
  --description "docker-runner-01" \
  --docker-image alpine:3.20

The most important parameters:

• --url — your GitLab instance address (https://gitlab.com/ for SaaS).
• --token — the registration token from the Runners page.
• --executor — the executor type used (docker, shell, kubernetes, etc.).
• --docker-image — the default image for jobs that don't write their own image keyword.

The registration result is stored in /etc/gitlab-runner/config.toml — here's the condensed version:

concurrent = 4
 
[[runners]]
  name = "docker-runner-01"
  url = "https://gitlab.com/"
  executor = "docker"
  [runners.docker]
    image = "alpine:3.20"
    privileged = false

#Tags: Routing Jobs to Specific Runners

Once a runner is registered, you can give it tags — labels that jobs use to choose which runner handles their work. Register with --tag-list:

gitlab-runner register \
  --url https://gitlab.com/ \
  --executor docker \
  --tag-list "docker,high-cpu"

Inside .gitlab-ci.yml, jobs use the tags keyword to request a runner with those labels:

deploy_prod:
  stage: deploy
  script:
    - ./deploy.sh
  tags:
    - docker
    - high-cpu

The deploy_prod job will only be picked up by a runner that has all of those tags. If no runner matches, the job will sit idle (stuck) forever. Rule of thumb: use tags for truly specific routing — like architecture (amd64), hardware (gpu), or job type (build, deploy) — not as a substitute for executor configuration.

#Verifying and Monitoring Runners

To make sure your runner is healthy and registered, use these commands:

gitlab-runner status
gitlab-runner list
glab runner list

#Common Mistakes

1. Stuck job (hanging pipeline status). The pipeline never finishes because no runner matches the requested tags, or the shared runner is down. Check the Runners page and the tag list.
2. Runner doesn't pick up untagged jobs. By default, a runner with tags only accepts jobs that also have tags. If you want a runner to accept all jobs, register it with --run-untagged=true.
3. Running a runner on a personal laptop. For production, don't run runners on your work machine — other people's code will execute on that machine. Use a VM, container, or dedicated server.

#Closing

In this episode 3, you've mastered the infrastructure side of GitLab CI/CD:

• Runner classifications: shared (entire instance), group (one organization), and specific (one project).
• Executor types: shell (directly on host), docker (isolated container, most popular), and kubernetes (dynamic pods).
• Registering runners with gitlab-runner register plus --url, --token, --executor, and --docker-image.
• Routing jobs with the tags keyword, plus verification with gitlab-runner status, gitlab-runner list, and glab runner list.

Your pipeline now has a clear workforce. In episode 4 we'll control when that work runs — dynamic control flow with rules and workflow: the legacy only/except vs modern rules, if, changes, exists conditions, the when parameter, and preventing duplicate pipelines with workflow: rules. See you in episode 4!