GitLab CI/CD Runner Setup Guide

GitLab Runner Containerized Setup

Using containerized runners is the industry standard for scalable, clean, and isolated execution of CI/CD jobs. This guide outlines how to configure a GitLab Runner locally using Docker Compose.

---

1. The Docker Compose Stack

To persist config and allow the runner to execute Docker containers (Docker-in-Docker), we mount /var/run/docker.sock and define a configuration volume in docker-compose.yml:

version: '3.8'

services:
  runner:
    image: gitlab/gitlab-runner:latest
    container_name: local_gitlab-runner
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/etc/gitlab-runner

---

2. Registering the Runner via glab CLI

You can register the runner to your GitLab project using the GitLab CLI (glab) and REST API:

# Register runner and get registration credentials
PROJECT_ID=$(glab repo view --output json --jq '.id')

RUNNER_JSON=$(glab api -X POST user/runners \
    -F runner_type=project_type \
    -F project_id="$PROJECT_ID" \
    -F tag_list="local-runner" \
    -F description="Local Docker Runner")

---

3. Registering the Runner inside the Container

Execute the registration wizard non-interactively inside the runner container:

docker exec local_gitlab-runner gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image "docker:stable" \
  --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"

Once registered, the configuration details are written to config/config.toml dynamically. You can spin down the stack anytime using docker-compose down.