Runners GitLab CI/CD

Vous savez maintenant écrire un fichier .gitlab-ci.yml avec des stages, des jobs et des scripts. Mais qui exécute réellement ces jobs ? Ce sont les runners — des agents qui récupèrent vos jobs et lancent les commandes. Ce guide vous explique comment ils fonctionnent et comment les optimiser.

En 30 secondes

• Runner = machine qui exécute les jobs
• Shared runners = fournis par GitLab, pour tout le monde
• Tags = cibler un runner spécifique (tags: [docker, linux])
• Executor = comment le runner exécute les jobs (Docker, Shell, K8s…)

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Comprendre le rôle d’un runner : l’agent qui exécute vos jobs
• Différencier shared, group et project runners : choisir le bon type selon vos besoins
• Utiliser les tags : cibler un runner spécifique pour un job
• Choisir un executor : Docker, Shell ou Kubernetes selon votre contexte
• Diagnostiquer un job “pending” : identifier pourquoi un job ne démarre pas
• Optimiser les performances : réduire les temps d’exécution

Prérequis

Avant de continuer, assurez-vous de maîtriser :

• Concepts fondamentaux GitLab CI/CD
• Écrire un fichier .gitlab-ci.yml

Qu’est-ce qu’un runner ?

Un runner est un agent qui :

1. Récupère les jobs en attente depuis GitLab
2. Exécute les commandes du job
3. Renvoie les résultats (logs, artefacts, statut)

Types de runners

Type	Portée	Cas d’usage
Shared runners	Tous les projets GitLab.com	Projets standards, pas de setup
Group runners	Projets d’un groupe	Équipes avec besoins communs
Project runners	Un seul projet	Sécurité, performance, besoins spécifiques

Glissez pour voir

Shared runners

GitLab.com fournit des runners partagés, gratuits (avec quotas). Ils sont :

• Préconfigurés avec Docker
• Disponibles immédiatement
• Limités en minutes par mois (selon votre plan)

Pour les utiliser, rien à configurer — vos jobs s’exécutent automatiquement dessus.

Dans Settings > CI/CD > Runners, vous voyez les runners disponibles pour votre projet : leur statut (online/offline), leurs tags, et s’ils sont partagés ou dédiés.

Group runners

Les group runners sont partagés entre tous les projets d’un groupe GitLab. Ils offrent un bon compromis entre les shared runners (trop génériques) et les project runners (trop isolés).

Cas d’usage :

• Équipes avec plusieurs projets partageant les mêmes besoins (stack technique commune)
• Gouvernance centralisée : un admin groupe gère les runners pour tous les projets
• Contrôle des tags et des accès au niveau équipe

Pour créer un group runner : Group > Settings > CI/CD > Runners > New group runner. Les projets du groupe l’utilisent automatiquement (sauf si désactivé au niveau projet).

Project runners (self-hosted)

Installez votre propre runner pour :

• Performance : machine dédiée, pas de file d’attente
• Sécurité : jobs qui accèdent à des ressources internes
• Spécialisation : GPU, ARM, outils spécifiques
• Coût : éviter les quotas de minutes

Visualiser l’exécution des jobs

Quand un pipeline s’exécute, vous pouvez suivre sa progression dans Build > Pipelines :

Chaque ligne représente un pipeline avec son statut, sa branche et son déclencheur. Cliquez sur un pipeline pour voir le détail des stages et jobs :

Ce graphe montre les stages (colonnes) et les jobs (cases). Les jobs d’un même stage s’exécutent en parallèle. Cliquez sur un job pour voir ses logs en temps réel :

Les logs affichent chaque commande exécutée et sa sortie. Vous voyez les variables CI (comme $CI_COMMIT_BRANCH) résolues avec leurs valeurs réelles.

Les executors

L’executor définit comment le runner exécute les jobs :

Executor	Description	Cas d’usage
Docker	Chaque job dans un conteneur isolé	Standard, isolation, reproductibilité
Docker+Machine	Crée des VMs à la demande (autoscaling)	Charge variable, cloud
Shell	Exécute directement sur la machine	Accès hardware, simplicité
Kubernetes	Pods Kubernetes éphémères	Cluster K8s existant
SSH	Se connecte à une machine distante	Déploiement sur serveurs existants

Glissez pour voir

Recommandation

Pour la plupart des cas, utilisez l’executor Docker. Il offre isolation et reproductibilité sans complexité.

Executor Docker

Le plus courant. Chaque job s’exécute dans un conteneur Docker.

job:
  image: node:18    # Image Docker utilisée
  script:
    - npm install
    - npm test

Avantages :

• Isolation complète entre jobs
• Environnement reproductible
• Large choix d’images disponibles

Inconvénients :

• Temps de pull de l’image
• Pas d’accès direct au hardware

Executor Shell

Exécute les commandes directement sur la machine du runner.

job:
  tags:
    - shell    # Cible un runner avec executor shell
  script:
    - ./build.sh

Avantages :

• Accès direct au hardware (GPU, USB…)
• Pas de overhead Docker
• Outils préinstallés disponibles

Inconvénients :

• Pas d’isolation entre jobs
• Dépendances à installer sur la machine

Les tags

Les tags permettent de cibler un runner spécifique. Un job avec des tags ne s’exécute que sur un runner qui a tous ces tags.

build:
  tags:
    - docker
    - linux
  script:
    - make build

build-arm:
  tags:
    - docker
    - arm64
  script:
    - make build

Côté runner, les tags sont définis lors de l’enregistrement :

gitlab-runner register \
  --tag-list "docker,linux,amd64"

Tags obligatoires

Si votre runner est configuré avec “Run untagged jobs: No”, il n’exécutera que les jobs avec des tags correspondants.

Installer un runner

Linux

1. Télécharger le binaire

   curl -L --output /usr/local/bin/gitlab-runner \
     https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
   chmod +x /usr/local/bin/gitlab-runner

2. Créer un utilisateur dédié

   useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

3. Installer et démarrer le service

   gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
   gitlab-runner start

4. Créer le runner dans GitLab

   Dans Settings > CI/CD > Runners, cliquez sur New project runner. Configurez les tags et options, puis GitLab génère un runner authentication token (préfixe glrt-).

5. Enregistrer le runner

   Utilisez le token glrt-... avec l’option --token :

   sudo gitlab-runner register \
     --url "https://gitlab.com/" \
     --token "glrt-XXXXXXXXXXXXXXXX" \
     --name "my-docker-runner" \
     --executor "docker" \
     --docker-image "alpine:3.19" \
     --tag-list "docker,linux"

Nouveau workflow d'enregistrement

Depuis GitLab 16.0, le workflow recommandé utilise des runner authentication tokens (glrt-...) créés via l’UI. L’ancienne méthode avec --registration-token est dépréciée et peut être désactivée sur certaines instances. Documentation officielle.

Docker

Alignez la version du runner avec votre version GitLab (ex: GitLab 17.x → Runner 17.x) :

export RUNNER_VERSION="17.8.0"  # Aligner avec votre version GitLab

docker run -d \
  --name gitlab-runner \
  --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  "gitlab/gitlab-runner:v${RUNNER_VERSION}"

Puis enregistrez avec le token glrt-... :

docker exec -it gitlab-runner gitlab-runner register \
  --url "https://gitlab.com/" \
  --token "glrt-XXXXXXXXXXXXXXXX"

Sécurité : montage docker.sock

Monter /var/run/docker.sock donne un accès root à l’hôte. Tout conteneur peut créer d’autres conteneurs privilégiés. Alternatives plus sûres :

• Kubernetes executor : pods éphémères isolés
• Docker-in-Docker (dind) avec --privileged limité
• Restreindre via allowed_images, allowed_services dans config.toml

Kubernetes

Utilisez le Helm chart officiel. Le runnerToken doit être un runner authentication token (glrt-...) créé via l’UI GitLab :

helm repo add gitlab https://charts.gitlab.io
helm install gitlab-runner gitlab/gitlab-runner \
  --set gitlabUrl=https://gitlab.com \
  --set runnerToken="glrt-XXXXXXXXXXXXXXXX" \
  --set rbac.create=true

Pour la production, utilisez un Secret Kubernetes plutôt que de passer le token en clair :

kubectl create secret generic gitlab-runner-secret \
  --from-literal=runner-token="glrt-XXXXXXXXXXXXXXXX"

helm install gitlab-runner gitlab/gitlab-runner \
  --set gitlabUrl=https://gitlab.com \
  --set runners.secret=gitlab-runner-secret \
  --set rbac.create=true

Configuration du runner

Le fichier de configuration est /etc/gitlab-runner/config.toml :

concurrent = 4        # Jobs simultanés max sur ce runner
check_interval = 3    # Intervalle de polling GitLab (en secondes)

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "glrt-xxxx"
  executor = "docker"

  [runners.docker]
    image = "alpine:3.19"
    privileged = false
    volumes = ["/cache"]
    pull_policy = ["always", "if-not-present"]  # Fallback si registry indisponible

Paramètres importants :

Paramètre	Description
concurrent	Nombre de jobs simultanés sur ce runner
check_interval	Intervalle entre les polls vers GitLab (réparti entre les runners du fichier)
pull_policy	Stratégie de pull : always, if-not-present, never (ou liste pour fallback)
privileged	Mode privilégié (requis pour Docker-in-Docker, risque sécurité)
volumes	Volumes montés dans les conteneurs

Glissez pour voir

pull_policy et sécurité

if-not-present améliore les performances mais présente un risque sur les runners partagés/publics : un utilisateur pourrait accéder à une image privée déjà en cache. Pour les runners multi-tenant, privilégiez always. Documentation sécurité.

Diagnostiquer un job pending

Votre job reste bloqué sur “pending” ? Voici les causes possibles :

Symptôme	Cause probable	Solution
”Waiting for a runner”	Aucun runner disponible	Vérifier que les runners sont actifs
”This job is stuck”	Tags ne matchent pas	Vérifier les tags du job et du runner
Pending longtemps	Tous les runners occupés	Augmenter concurrent ou ajouter des runners
Pending puis fail	Runner offline	Vérifier le service gitlab-runner

Glissez pour voir

Diagnostic :

# Vérifier le statut du runner
gitlab-runner status

# Voir les runners enregistrés
gitlab-runner list

# Tester la connexion à GitLab
gitlab-runner verify

Dans GitLab : Settings > CI/CD > Runners montre les runners disponibles et leur statut (voir la capture plus haut).

Pourquoi mes jobs sont lents ?

Cause	Impact	Solution
Pull d’image à chaque job	+30s à +2min	pull_policy: if-not-present
npm install à chaque job	+1 à 5min	Utiliser le cache
Runners partagés surchargés	File d’attente	Runner dédié
Image lourde	Temps de téléchargement	Image plus légère ou custom

Glissez pour voir

Optimisation rapide

Le cache GitLab CI est le levier le plus efficace. Un npm install passe de 2 minutes à 10 secondes avec un cache correctement configuré.

pull_policy: if-not-present est pertinent sur un runner privé et maîtrisé. Pour un runner partagé ou public, privilégiez always (risques liés aux images privées en cache).

Bonnes pratiques

1. Utilisez des tags significatifs : docker-linux, gpu, prod-deploy
2. Limitez les runners de production : tags dédiés, accès restreint
3. Configurez concurrent correctement : selon les ressources de la machine
4. Utilisez pull_policy: if-not-present : évite les pulls inutiles
5. Surveillez vos runners : dashboards, alertes si offline

À retenir

1. Runner = agent qui exécute les jobs sur une machine
2. Shared runners gratuits (avec quotas), project runners pour contrôle total
3. Executor Docker recommandé pour l’isolation et la reproductibilité
4. Tags = cibler un runner spécifique (tags: [docker, gpu])
5. Job pending = vérifier tags, runners actifs, et concurrent
6. Performance = cache, pull_policy, runners dédiés

Contrôle des connaissances

Testez vos connaissances sur les runners GitLab CI/CD.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Artefacts et cache Optimiser les performances avec le cache et les artefacts.

Debug pending Pourquoi mon job reste en attente ? Problèmes de runners.

Installation runner Installer et configurer votre propre runner.

×

📖 Voir la documentation →