GitLab Runner : installation, enregistrement et configuration

GitLab Runner est le processus qui exécute vos jobs CI/CD. Sans lui, vos pipelines restent bloqués en attente. Ce guide vous montre comment l’installer sur Linux, le connecter à votre instance GitLab avec le token d’authentification runner (glrt-), et le configurer correctement pour la production. À la fin, votre runner est opérationnel, l’executor choisi en connaissance de cause, et le fichier config.toml compris.

Prérequis : une instance GitLab accessible (guide d’installation), et un serveur Linux (Ubuntu 22.04/24.04 ou RHEL/Rocky 8/9).

Qu’est-ce que GitLab Runner ?

GitLab Runner est un agent léger distinct de GitLab qui :

reçoit des jobs depuis GitLab via une connexion sortante (pas de port entrant à ouvrir)
exécute chaque job dans l’environnement défini par l’executor (shell, conteneur Docker, pod Kubernetes…)
renvoie les logs et le résultat à GitLab en temps réel

Un runner peut être partagé (disponible pour toute l’instance), de groupe (disponible pour plusieurs projets), ou de projet (dédié).

Choisir son executor

L’executor détermine l’environnement d’exécution de chaque job. Choisir le mauvais executor est la première source de problèmes en production.

Executor	Isolation	Sécurité	Cas d’usage recommandé
Shell	Aucune — jobs sur l’hôte direct	⚠️ Déconseillé pour jobs non fiables	CI interne contrôlé, scripts admin système
Docker	Conteneur isolé par job	Bonne (éviter `privileged: true`)	Cas général — meilleur compromis simplicité/isolation
Kubernetes	Pod éphémère par job	Bonne avec RBAC en place	Cluster K8s déjà opéré
Instance (Autoscaler)	VM éphémère par job	Excellente	Workloads variables, isolation forte requise
VirtualBox	VM complète	Excellente	Legacy, builds Windows, tests multi-OS

Recommandation : commencez par Docker si vous hésitez. C’est l’executor le plus documenté, le plus facile à déboguer, et il couvre 90 % des cas. Si vous opérez Kubernetes, lisez le guide runner Kubernetes.

Installer GitLab Runner

Prérequis matériels

Composant	Minimum	Recommandé (prod)
CPU	1 vCPU	2+ vCPU
RAM	512 Mo	2 Go+
Disque	10 Go	20 Go+ SSD
OS	Ubuntu 20.04+, RHEL 8+	Ubuntu 22.04 / Rocky 9

GitLab Runner est un binaire Go — ses besoins propres sont faibles. La RAM nécessaire dépend principalement des jobs (images Docker téléchargées, artefacts compilés…).

# Ajout du dépôt GitLab Runner
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# Installation
sudo apt-get install -y gitlab-runner

# Vérification
gitlab-runner --version

# Ajout du dépôt
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash

# Installation
sudo dnf install -y gitlab-runner

# Vérification
gitlab-runner --version

Résultat attendu de gitlab-runner --version :

Version:      18.x.x
Git revision: xxxxxxxx
Git branch:   18-x-stable
GO version:   go1.24.x
Built:        2025-XX-XX HH:MM:SS
OS/Arch:      linux/amd64

Depuis GitLab Runner 17.7.1, l’installation d’une version précise nécessite deux packages :

# Debian / Ubuntu
sudo apt-get install gitlab-runner=18.10.0 gitlab-runner-helper-images=18.10.0

# RHEL / Rocky / AlmaLinux
sudo dnf install gitlab-runner-18.10.0 gitlab-runner-helper-images-18.10.0

Le package gitlab-runner-helper-images contient les images Docker utilisées par l’executor pour préparer et nettoyer les jobs. Sans lui, les jobs peuvent échouer avec une erreur helper image not found.

Créer et enregistrer un runner

Depuis GitLab 15.x, les runners sont créés depuis l’interface GitLab, qui génère un runner authentication token (glrt-). L’ancienne méthode par --registration-token est dépréciée.

Étape 1 — Créer le runner dans l’UI

Accédez au bon niveau selon la portée souhaitée :
- Runner d’instance : Menu Admin → CI/CD → Runners → New instance runner
- Runner de groupe : Groupe → Build → Runners → New group runner
- Runner de projet : Projet → Settings → CI/CD → Runners → New project runner
Remplissez le formulaire :
- Tags (optionnel) : docker,build,linux — les jobs avec ces tags seront dirigés vers ce runner
- Cochez Run untagged jobs si ce runner doit prendre tous les jobs sans tag
- Décochez Lock to current project pour un runner réutilisable
Cliquez sur “Create runner”.

GitLab affiche le runner authentication token — il commence par glrt-.

Ce token n’est affiché qu’une seule fois. Copiez-le immédiatement. Si vous l’oubliez, il faut créer un nouveau runner.

Étape 2 — Enregistrer le runner sur le serveur

Sur le serveur où GitLab Runner est installé :

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.monentreprise.internal" \
  --token "glrt-xxxxxxxxxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "runner-docker-prod-01"

GitLab Runner ajoute la configuration dans /etc/gitlab-runner/config.toml.

Vérification :

sudo gitlab-runner list

Résultat attendu :

Listing configured runners         ConfigFile=/etc/gitlab-runner/config.toml
runner-docker-prod-01              Executor=docker Token=glrt-xxxx URL=https://gitlab.monentreprise.internal

Vérification dans l’UI GitLab : Admin → CI/CD → Runners — le runner doit apparaître avec un état vert (online).

Liste des runners dans l'interface GitLab CI/CD Settings

Étape 3 — Démarrer le service

# Démarrer et activer au boot
sudo systemctl enable --now gitlab-runner

# Vérifier le statut
sudo systemctl status gitlab-runner

Résultat attendu :

● gitlab-runner.service - GitLab Runner
     Loaded: loaded (/lib/systemd/system/gitlab-runner.service; enabled)
     Active: active (running) since ...

Comprendre et personnaliser config.toml

Le fichier /etc/gitlab-runner/config.toml est modifiable directement. GitLab Runner recharge la configuration sans redémarrage.

Structure générale

# Nombre maximum de jobs exécutés en parallèle sur ce runner
concurrent = 4

# Intervalle de vérification des jobs (secondes)
check_interval = 3

# Niveau de log : debug, info, warn, error
log_level = "info"
log_format = "runner"

[[runners]]
  name = "runner-docker-prod-01"
  url = "https://gitlab.monentreprise.internal"
  id = 12
  token = "glrt-xxxxxxxxxxxxxxxxxxxx"
  token_obtained_at = 2024-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"

  [runners.docker]
    # Image par défaut si le job ne la précise pas
    image = "alpine:latest"

    # Ne pas activer privileged sans raison documentée
    privileged = false

    # Répertoire de volume scratch
    volumes = ["/cache"]

    # Politique de téléchargement d'image
    pull_policy = ["always"]

Paramètres importants

Paramètre	Valeur recommandée	Effet
`concurrent`	4 (ajuster selon CPU/RAM)	Jobs simultanés sur ce runner
`privileged`	`false`	Évite l’escalade de privilèges vers l’hôte
`pull_policy`	`["always"]` en prod	Garantit des images fraîches
`volumes`	`["/cache"]`	Partage de cache entre jobs
`clone_url`	URL interne GitLab	Si le réseau ne résout pas l’URL externe depuis le conteneur

Activer le cache

Le cache accélère les jobs en réutilisant les artefacts entre les exécutions. En production, préférez un cache S3 (MinIO ou AWS S3) :

[[runners]]
  # ...
  [runners.cache]
    Type = "s3"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "minio.monentreprise.internal"
      BucketName = "gitlab-runner-cache"
      Insecure = false

Pour un lab ou un poste de développement, le cache local suffit :

[runners.cache]
  Type = "local"

Sécurité opérationnelle

Ne jamais activer `privileged = true` sans justification

Avec privileged = true, le conteneur du job accède aux devices de l’hôte — c’est équivalent à donner un accès root à quiconque peut déclencher un pipeline.

Si vos jobs doivent construire des images Docker, préférez des outils rootless :

Kaniko — build sans Docker daemon
Buildah — alternative rootless to Docker

Isoler les runners par projet sensible

Déployez des runners dédiés pour les projets manipulant des secrets ou déployant en production. Un runner partagé entre projets peut exposer du cache ou des variables d’un projet à l’autre en cas de mauvaise configuration.

Maintenez GitLab Runner à jour

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install --only-upgrade gitlab-runner

# RHEL/Rocky
sudo dnf update gitlab-runner

Vérifiez l’utilisateur système

GitLab Runner tourne par défaut avec l’utilisateur gitlab-runner. Ne jamais l’exécuter en root :

ps aux | grep gitlab-runner
# → doit afficher l'utilisateur gitlab-runner, pas root

Variables secrètes

Ne jamais stocker de secrets dans config.toml ou dans les variables de pipeline en clair. Utilisez les variables CI/CD GitLab avec le type Masked ou Protected.

Dépannage : problèmes courants

Symptôme	Cause probable	Solution
Runner “offline” dans l’UI	Service arrêté ou token expiré	`systemctl status gitlab-runner` + vérifier le token
Job bloqué en “pending”	Aucun runner disponible ou tags incompatibles	Vérifier les tags du runner vs les tags du job
`ERROR: Preparing environment`	Image Docker introuvable	`docker pull <image>` depuis le serveur runner
`certificate signed by unknown authority`	CA privée non installée	Ajouter `tls_ca_file` dans `config.toml`
Runner absent après `register`	Mauvais URL ou token invalide	Vérifier l’URL et régénérer un token depuis l’UI
Jobs lents au démarrage	`pull_policy = "always"` sur réseau lent	Utiliser `["if-not-present", "always"]` en dev

Commandes de diagnostic :

# Logs du service en temps réel
sudo journalctl -fu gitlab-runner

# Tester la connexion à GitLab
sudo gitlab-runner verify

# Lister les runners configurés
sudo gitlab-runner list

À retenir

GitLab Runner est un agent distinct de GitLab — connexion sortante uniquement, pas de port entrant.
Depuis GitLab 15.x, les runners sont créés dans l’UI GitLab, qui génère un token glrt-. L’ancien --registration-token est déprécié depuis GitLab 17.0.
L’executor Docker est le bon choix par défaut. Évitez Shell sur des runners partagés.
privileged = false est la valeur sécurisée par défaut — ne jamais l’activer sans justification documentée.
Le fichier /etc/gitlab-runner/config.toml est l’unique source de vérité pour la configuration.
GitLab Runner recharge config.toml automatiquement — pas besoin de redémarrer le service.

Prochaines étapes

Runner Kubernetes Exécuter les jobs dans des pods éphémères sur votre cluster Kubernetes.

Installer GitLab self-managed Déployer GitLab CE sur un serveur Linux avec le package Omnibus.