GitLab Runner : erreurs courantes, causes profondes et correctifs fiables (avec exemples pratiques)

Intro

GitLab Runner est le moteur derrière vos jobs CI/CD. Quand il tombe en panne, les pipelines se bloquent et les journaux sont parfois obscurs. Ce guide propose une méthode éprouvée pour diagnostiquer et corriger rapidement les erreurs de runner les plus courantes, en toute sécurité. Vous apprendrez à inventorier votre environnement, appliquer des changements de configuration ciblés, valider les correctifs avec des commandes concrètes et restaurer un état stable sans casser les pipelines qui fonctionnent.

1) Dressez l’inventaire du runner et de l’environnement

Commencez par noter précisément ce qui tourne. Les versions et les exécutants (executors) déterminent autant les messages d’erreur que les correctifs.

• Version du runner et plateforme :

gitlab-runner --version

• Runners enregistrés et executors :

gitlab-runner list

• Si vous utilisez l’executor Docker :

docker --version
docker info | sed -n '1,20p'

• Si le runner lui-même tourne dans Docker :

docker ps --filter name=gitlab-runner --format '{{.Names}}  {{.Image}}'

• Si vous utilisez l’executor Kubernetes :

kubectl version --short
kubectl get nodes

Notez aussi :

• Système d’exploitation et architecture (Linux/Windows/macOS; amd64/arm64).
• Mode réseau (host/bridge), proxys, DNS personnalisés, et si une inspection TLS ou une AC (CA) d’entreprise s’applique.
• Si les jobs exigent le mode privilégié (Docker-in-Docker, BuildKit) ou des volumes spécifiques.

2) Appliquez des changements sûrs et ciblés

Adoptez un flux de travail délibéré pour éviter d’introduire de nouvelles pannes.

1. Sauvegardez la configuration d’abord :

• Paquet Linux : /etc/gitlab-runner/config.toml
• Runner dans Docker : docker cp gitlab-runner:/etc/gitlab-runner/config.toml ./config.toml.bak

1. Éditez uniquement la portée du runner concerné (évitez les changements globaux sauf nécessité). Exemple : étendre un délai d’expiration pour un runner précis :

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "..."
  executor = "docker"
  timeout = 3600

1. Validez le runner et rechargez :

gitlab-runner verify
# Paquets Linux
sudo systemctl restart gitlab-runner
# Runner dans Docker
docker restart gitlab-runner

1. Utilisez un job minimal pour confirmer le comportement avant de relancer les pipelines de production :

# .gitlab-ci.yml
verify-runner:
  image: alpine:3
  script:
    - echo "Runner OK"
    - apk add --no-cache curl >/dev/null 2>&1 || true

3) Erreurs courantes, causes profondes et correctifs pratiques

3.1 exec: "docker": executable file not found in $PATH

• Quand : executor Docker mais le binaire Docker est absent ou inaccessible.
• Vérifications et correctifs :
• Assurez-vous que Docker est installé et démarré sur l’hôte :
• Ubuntu/Debian : sudo apt-get update && sudo apt-get install -y docker.io
• RHEL/CentOS : sudo yum install -y docker et sudo systemctl enable --now docker
• Vérifiez que le binaire est résolu :

which docker && docker info

• Si le runner tourne dans un conteneur, utilisez le socket Docker ou Docker-in-Docker :
• Montage du socket : -v /var/run/docker.sock:/var/run/docker.sock
• Service DinD (requiert privileged) :

[runners.docker]
  privileged = true
  services = ["docker:24-dind"]

3.2 ERROR: Job failed: exit code 1

• Quand : échec générique; un script du job a échoué.
• Diagnostic :
• Repérez la dernière commande non vide dans le journal du job.
• Reproduisez en local avec la même image et le même répertoire de travail :

docker run --rm -v "$PWD":/builds/project -w /builds/project my-image:latest sh -lc "<the failing command>"

• Pistes de correction :
• Vérifiez que les outils requis sont présents dans l’image ou installez-les dans le job.
• Rendez la commande verbeuse (ex. set -euxo pipefail, npm --verbose, mvn -X).

3.3 dial tcp: lookup gitlab.example.com: no such host

• Quand : échec de résolution DNS sur l’hôte du runner ou dans le conteneur du job.
• Diagnostic :

nslookup gitlab.example.com || dig gitlab.example.com +short

• Correctifs possibles :
• Définissez des résolveurs DNS valides sur l’hôte (/etc/resolv.conf) ou dans le démon Docker (/etc/docker/daemon.json) :

{
  "dns": ["1.1.1.1", "8.8.8.8"]
}

• Pour les cas tenaces, testez le réseau host dans la config Docker du runner :

[runners.docker]
  network_mode = "host"

• Si un DNS ou un proxy d’entreprise est requis, ajoutez les variables d’environnement et no_proxy au runner :

[runners]
  environment = ["http_proxy=http://proxy:3128", "https_proxy=http://proxy:3128", "no_proxy=localhost,127.0.0.1,.example.com"]

3.4 SSL certificate problem: unable to get local issuer certificate

• Quand : interception TLS d’entreprise (MITM) ou CA privée; certificat de GitLab ou du registre non approuvé.
• Correctifs :
• Installez la CA sur l’hôte du runner (Linux) : placez corp-ca.crt dans /usr/local/share/ca-certificates/ puis sudo update-ca-certificates.
• Pour les jobs Docker, intégrez la CA dans l’image ou montez-la et définissez les variables d’env. :

variables:
  SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt

• Pour GitLab Runner, utilisez tls-ca-file dans config.toml si nécessaire :

[[runners]]
  tls-ca-file = "/etc/gitlab-runner/corp-ca.crt"

3.5 permission denied (checkout, cache, artifacts, ou workspace)

• Quand : UIDs/GIDs non concordants, montages restrictifs, ou utilisateur non-root dans le conteneur.
• Diagnostic :

id
ls -ld /builds /cache

• Correctifs possibles :
• Exécutez le conteneur avec un utilisateur correspondant ou en root :

[runners.docker]
  user = "root"

• Alignez les permissions sur l’hôte :

sudo chown -R gitlab-runner:gitlab-runner /var/lib/gitlab-runner
sudo chmod -R u+rwX /var/lib/gitlab-runner

• Sous Kubernetes, définissez securityContext ou utilisez une image compatible non-root.

3.6 Cache is not found (cache non restauré)

• Quand : clé de cache différente, mauvais chemins, ou cache externe mal configuré.
• Correctifs :
• Utilisez une clé stable avec des repli(s) et des chemins clairs :

cache:
  key:
    files:
      - package-lock.json
    prefix: "node"
  fallback_keys:
    - "node"
  paths:
    - node_modules/

• Pour un cache S3/MinIO, validez les identifiants et le bucket :

gitlab-runner verify --delete
gitlab-runner cache-archiver --help

• Gardez les chemins petits et spécifiques; évitez de mettre en cache des sorties de build qui changent constamment.

3.7 Failed to remove network: network ... not found / ressources Docker orphelines

• Quand : nettoyage interrompu ou redémarrages du démon.
• Correctif :

sudo systemctl restart docker || true
docker network prune -f
docker container prune -f
docker image prune -f

• Envisagez un job de nettoyage périodique sur l’hôte du runner.

3.8 This job is stuck; no runners online or no matching tags

• Quand : runner hors ligne, en pause, non assigné au projet, ou étiquettes (tags) non concordantes.
• Diagnostic et correctifs :
• Dans l’interface GitLab, confirmez que le runner est en ligne et non en pause.
• Vérifiez les tags du job et du runner. Ils doivent s’entrecouper :

lint:
  tags: [docker, amd64]

• Assurez-vous que le runner est partagé ou assigné au projet et non verrouillé sur un autre projet.
• Augmentez la concurrence si toutes les builds sont en file d’attente :

concurrent = 4

3.9 pull access denied / image not found / rate limited

• Quand : registre privé sans authentification ou limites Docker Hub.
• Correctifs :
• Fournissez des identifiants de registre via DOCKER_AUTH_CONFIG :

variables:
  DOCKER_AUTH_CONFIG: >
    {"auths": {"registry.example.com": {"auth": "<base64(user:pass)>"}}}

• Ou connectez-vous pendant before_script :

before_script:
  - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"

• Figez les images sur des digests pour éviter les surprises :

image: alpine@sha256:1b231...

3.10 Les builds Docker-in-Docker échouent sans privileged ou avec des cgroups imbriqués

• Quand : vous utilisez docker:dind mais le runner n’a pas privileged ou les montages requis.
• Correctif :

[runners.docker]
  privileged = true
  volumes = ["/certs/client", "/cache"]
  services = ["docker:24-dind"]

• Si les builds nécessitent BuildKit, activez-le explicitement :

variables:
  DOCKER_BUILDKIT: "1"

3.11 Échec du git clone : Host key verification failed ou erreurs d’authentification

• Quand : clé d’hôte SSH inconnue ou jetons/identifiants manquants.
• Correctifs possibles :
• Privilégiez HTTPS avec CI_JOB_TOKEN (par défaut dans GitLab) et assurez-vous que la CA d’entreprise est installée en cas d’inspection TLS.
• En SSH, ajoutez la clé d’hôte connue dans le job :

before_script:
  - mkdir -p ~/.ssh && chmod 700 ~/.ssh
  - ssh-keyscan -t rsa gitlab.example.com >> ~/.ssh/known_hosts

4) Flux de vérification et de diagnostic

Appliquez les étapes suivantes après chaque changement :

• Vérifiez la vivacité du runner :

gitlab-runner verify

• Exécutez un pipeline minimal (le job verify-runner ci-dessus) et confirmez le succès.
• Activez temporairement les journaux de debug :

gitlab-runner --debug run

• Avec l’executor Docker, comparez le comportement hôte vs conteneur avec la même image pour isoler les différences d’environnement.

5) Plan de reprise

Prévoyez une marche arrière pour chaque changement.

• config.toml mal formé (le runner ne démarre plus) :

sudo cp /etc/gitlab-runner/config.toml.bak /etc/gitlab-runner/config.toml
sudo systemctl restart gitlab-runner

• Épuisement des ressources (no space left on device / cannot allocate memory) :

df -h
free -h
# Nettoyage
gitlab-runner cleanup || true
docker system prune -af --volumes

• Les changements de mode réseau cassent la connectivité : testez puis revenez vite en arrière.

nc -vz gitlab.example.com 443 || curl -vkI https://gitlab.example.com
# En cas d’échec, revenez sur network_mode ou les paramètres de proxy

• Conteneur du runner en mauvaise santé : recréez-le depuis une image de référence et réutilisez le même config.toml.

6) Tableau de référence rapide

7) Liste de contrôle opérationnelle

À exécuter chaque semaine ou lors d’un dépannage :

• Le runner est vivant : gitlab-runner verify
• Aucun job bloqué dans l’interface GitLab; les tags correspondent
• Utilisation disque < 80 % : df -h; purge Docker : docker system prune -af
• Sauvegarde à jour : copier config.toml et documenter les changements
• Relire les logs du runner pour repérer de nouveaux avertissements

Conclusion

Le dépannage de GitLab Runner devient prévisible avec un processus clair : inventorier l’environnement, changer un paramètre à la fois, valider avec un job minimal, et toujours garder un plan de repli. Servez-vous des correctifs d’erreurs courantes de ce guide comme points de départ, puis documentez ce qui fonctionne dans votre contexte. Au fil du temps, vos runners seront plus rapides à réparer, plus simples à opérer et beaucoup moins susceptibles de bloquer des pipelines critiques.