Dépannage de GitLab Runner avec exemples pratiques : guide d'implémentation

Lorsqu'un GitLab Runner cesse de récupérer des jobs, échoue à un checkout ou dépasse le délai d'envoi d'artefacts, la pression est réelle : le développement ralentit et les fenêtres de déploiement glissent. Ce guide vous offre une méthode fiable et à faible risque pour diagnostiquer et corriger les problèmes courants de GitLab Runner à l'aide d'exemples de commandes pratiques, de modifications de configuration ciblées et d'étapes réversibles. Vous ferez l'inventaire de votre environnement, choisirez un chemin de configuration sécurisé, vérifierez le comportement avec des résultats attendus et résoudrez les modes de défaillance fréquents. L'objectif est de passer de la confusion à un dépannage répétable et mesuré en lequel vous pouvez avoir confiance.

Inventaire des versions et de l'environnement

Avant de changer quoi que ce soit, capturez un inventaire simple. Cela rend votre travail mesurable et le retour en arrière plus sûr.

Prérequis

• Accès shell aux hôtes du runner
• Permissions pour consulter les journaux système et modifier les fichiers de configuration du runner
• Accès aux paramètres de projet et de groupe GitLab (pour voir les runners, les jetons et les journaux de jobs)

Informations de version minimales à capturer

• Version de GitLab Runner et méthode d'installation
• Version du serveur GitLab (auto-hébergé ou SaaS)
• Type d'exécuteur par runner : shell, Docker, Kubernetes ou autres
• Système d'exploitation et système d'init (systemd, upstart, services Windows)
• Contraintes réseau : proxys, pare-feux, registres privés, DNS

Commandes et emplacements

Linux/macOS :

• Afficher la version du runner :

  gitlab-runner --version

Windows (PowerShell) :

  gitlab-runner --version

• Lister les runners configurés sur l'hôte :

  sudo gitlab-runner list

Résultat attendu : noms des runners avec hachages courts des jetons et types d'exécuteur.

• Trouver le fichier de configuration :
• Linux par défaut : /etc/gitlab-runner/config.toml
• Windows par défaut : C:\GitLab-Runner\config.toml

• État du service (Linux systemd) :

  systemctl status gitlab-runner

• Journaux (Linux avec systemd) :

  journalctl -u gitlab-runner -n 200 --no-pager

Exemple construit : instantané d'inventaire

• GitLab Runner 16.7, installation par paquet sur Ubuntu 22.04
• Deux runners : exécuteurs shell et Docker
• GitLab.com SaaS
• Sortant via proxy d'entreprise
• Service systemd actif depuis 5 jours

Pourquoi cela importe

Les changements sont plus faciles à raisonner lorsque vous pouvez comparer le comportement avant et après. Conservez cet inventaire avec horodatages pour pouvoir revenir précisément en arrière si nécessaire.

Chemin de configuration sécurisé

Le dépannage doit commencer par le changement le plus petit et le plus sûr, et s'étendre seulement si requis. Suivez ce chemin et sauvegardez avant les modifications.

Étapes de sécurité

1. Sauvegarder la configuration du runner :

Linux :

   sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak.$(date +%Y%m%d%H%M%S)
   sudo chmod 600 /etc/gitlab-runner/config.toml.bak.*

Windows (PowerShell) :

   Copy-Item C:\GitLab-Runner\config.toml C:\GitLab-Runner\config.toml.bak.$(Get-Date -Format yyyyMMddHHmmss)

1. Éviter les changements globaux. Modifier seulement la section du runner spécifique dans config.toml.
2. Changer une chose à la fois. Après chaque changement, redémarrer le service et vérifier.
3. Tenir un journal de changements simple : horodatage, ce qui a changé, pourquoi, effet attendu.

Exemples de configuration ciblée

Dans /etc/gitlab-runner/config.toml (exemple construit), définissez d'abord une limite conservatrice :

• Ajuster la concurrence de façon sécurisée :

  concurrent = 2
  check_interval = 0

Effet attendu : au maximum 2 jobs concurrents à travers tous les runners sur cet hôte.

• Démarrer le runner en mode debug interactif pour éviter la verbosité persistante :

  sudo gitlab-runner run --debug

Appuyez sur Ctrl+C quand terminé. Pour une journalisation debug persistante, préférez les filtres du journal système plutôt que de changer le niveau de log du runner globalement.

• Définir les variables d'environnement dans la section du runner seulement, pas au niveau système :

Configuration de proxy réseau (exemple construit) :

  runners
    name = "shell-runner"
    executor = "shell"
    environment = [
      "HTTPS_PROXY=http://proxy.corp.example:8080",
      "NO_PROXY=localhost,127.0.0.1,.svc,.local"
    ]

Effet attendu : seul ce runner utilise le proxy ; localhost et les adresses locales au cluster le contournent.

Redémarrage sécurisé

• Linux systemd :

  sudo systemctl restart gitlab-runner
  sudo systemctl is-active gitlab-runner

• Windows :

  Restart-Service gitlab-runner
  Get-Service gitlab-runner

Vérification et diagnostics

La vérification signifie produire un résultat observable et attendu. Commencez étroit et local, puis élargissez.

Vérifications de santé de base

• Le runner peut atteindre GitLab :

  gitlab-runner verify --delete

Résultat attendu : liste les runners enregistrés et indique s'ils sont accessibles. Utilisez avec prudence ; le drapeau --delete supprime les références de runners inaccessibles du cache local, pas de GitLab.

• Le service démarre proprement :

  systemctl status gitlab-runner
  journalctl -u gitlab-runner -n 50 --no-pager

Résultat attendu : pas de boucles de plantage, pas de permission refusée sur les chemins de configuration ou de cache.

• Dans l'interface GitLab, confirmez que le runner apparaît comme en ligne. Sinon, ré-enregistrez de façon sécurisée :

Validité du jeton :

  sudo gitlab-runner register

Utilisez un jeton d'enregistrement non-admin limité au groupe ou au projet. Résultat attendu : le runner reçoit un jeton unique et apparaît en ligne.

• Intégrité du système de fichiers (Linux) :

  df -h
  getent passwd gitlab-runner || id gitlab-runner
  sudo -u gitlab-runner touch /tmp/runner-perm-check

Résultat attendu : espace libre suffisant ; l'utilisateur gitlab-runner existe et peut créer des fichiers dans temp.

• Accessibilité DNS et réseau :

  getent hosts gitlab.com || nslookup gitlab.com
  curl -sI https://gitlab.com/.well-known/security.txt | head -n 1

Résultat attendu : le DNS résout ; une ligne de statut HTTP 200/301/302 apparaît.

Vérifications ciblées par exécuteur

• Exécuteur shell : Assurez-vous que les outils requis sont dans le PATH pour l'utilisateur du service.

  sudo -u gitlab-runner which git bash sh

Résultat attendu : les chemins se résolvent. Sinon, ajoutez au PATH dans l'environnement du runner.

• Exécuteur Docker (exemple construit) : Confirmez que l'hôte peut contacter le registre.

  docker info
  docker login REGISTRY_URL
  docker pull alpine:3.18

Résultat attendu : pas d'erreurs TLS ou d'authentification. Si vous utilisez un certificat auto-signé, placez-le dans le magasin de confiance du moteur comme documenté pour votre OS.

• Exécuteur Kubernetes (exemple construit) :

  kubectl get nodes
  kubectl auth can-i create pods --as system:serviceaccount:runner-namespace:runner-sa

Résultat attendu : le compte de service utilisé par le runner peut créer des pods ; les nœuds sont Ready.

Motifs de journaux à surveiller

• authentification : jeton invalide, 403, runner non autorisé
• réseau : délai de contexte dépassé, délai d'entrée/sortie, délai de négociation TLS
• exécuteur : non trouvé, permission refusée, périphérique ou ressource occupé
• artefacts/cache : 403 lors de l'envoi, identifiants invalids, bucket non trouvé

Exemple construit : job bloqué en attente

• Observé : le job est en attente depuis 10+ minutes. Le runner est hors ligne dans l'interface.
• Vérifications : l'état du service montre une boucle de plantage ; les journaux indiquent permission refusée sur /var/lib/gitlab-runner.
• Correction : changer le propriétaire du répertoire pour l'utilisateur du runner et redémarrer.

  sudo chown -R gitlab-runner:gitlab-runner /var/lib/gitlab-runner
  sudo systemctl restart gitlab-runner

Résultat attendu : le runner apparaît en ligne ; les jobs en attente démarrent dans les limites de concurrence.

Modes de défaillance et récupération

Utilisez le tableau pour mapper rapidement un symptôme aux premières vérifications et actions. Suivez ensuite les flux de travail détaillés ci-dessous.

Les exemples construits sont identifiés ci-dessous.

1. Runner hors ligne ou non autorisé

Vérifications :

• Interface : statut du runner hors ligne
• Hôte : service en cours mais journaux montrent non autorisé ou jeton invalide

Étapes de récupération :

• Ré-enregistrer avec un jeton limité :

  sudo gitlab-runner register

Choisissez la bonne URL GitLab et entrez le jeton d'enregistrement du projet ou du groupe. Attribuez des étiquettes qui correspondent à vos jobs.

• Confirmez que le nom et les étiquettes du runner dans config.toml correspondent aux attentes.
• Redémarrez le service et vérifiez le statut en ligne.

Retour en arrière : Si le nouvel enregistrement a créé un doublon, désactivez l'ancien runner dans l'interface et supprimez sa section de config.toml après avoir confirmé qu'aucun job ne l'utilise.

2. Jobs bloqués en attente à cause d'incompatibilité d'étiquettes ou de concurrence (exemple construit)

Vérifications :

• Le job requiert les étiquettes : linux, shell
• Étiquettes du runner : seulement linux
• concurrent = 0 dans la config

Étapes de récupération :

• Ajoutez l'étiquette manquante ou supprimez l'exigence d'étiquette de job inutile.
• Définissez une concurrence sécurisée :

  concurrent = 2

• Redémarrez et surveillez la file d'attente.
• Résultat attendu : les jobs commencent dans la minute ; la profondeur de file diminue.

Retour en arrière : Si une charge élevée cause de la contention de ressources, réduisez concurrent à 1 temporairement.

3. Échecs de checkout ou d'authentification Git

Symptômes :

• fatal: could not read Username for https://... No such device or address
• Host key verification failed

Vérifications :

• Vérifiez les clés SSH ou les identifiants HTTPS pour l'utilisateur du runner.
• Pour SSH : remplissez known_hosts pour l'utilisateur du runner :

  sudo -u gitlab-runner ssh-keyscan -t rsa gitlab.com >> ~gitlab-runner/.ssh/known_hosts
  sudo chmod 600 ~gitlab-runner/.ssh/known_hosts

Étapes de récupération :

• Si vous utilisez HTTPS avec un jeton, assurez-vous que la variable est masquée et disponible au job.
• Validez l'URL et les identifiants en clonant manuellement comme l'utilisateur du runner.

Retour en arrière : Annulez les récentes modifications de variables d'identifiants si le dernier état connu bon fonctionnait.

4. Erreurs d'envoi/téléchargement d'artefacts et de cache (exemple construit)

Symptômes :

• 403 lors de l'envoi au point de terminaison d'artefacts ou au magasin compatible S3
• Le cache se recalcule toujours

Vérifications :

• Validez les paramètres du projet ou du groupe pour artefacts et cache.
• Inspectez la clé de cache utilisée par le job ; assurez-vous qu'elle est stable et non écrasée à chaque exécution inutilement.

Étapes de récupération :

• Définissez des clés de cache explicites et stables dans la définition du job pour éviter les échecs de cache :

  cache:
    key: "deps-v1"
    paths:
      - vendor/

• Pour les magasins de cache externes, exportez les identifiants via l'environnement du runner plutôt que de les coder en dur dans les scripts.

Retour en arrière : Si vous changez le backend de cache, conservez le backend précédent configuré jusqu'à ce que le nouveau ait des succès sur plusieurs jobs.

5. Problèmes de réseau et de proxy

Symptômes :

• Délai d'entrée/sortie vers GitLab ou les registres
• Délai de négociation TLS derrière un proxy

Vérifications :

• curl vers les points de terminaison GitLab avec et sans proxy
• NO_PROXY inclut les hôtes internes et 127.0.0.1

Étapes de récupération :

• Définissez HTTPS_PROXY et NO_PROXY seulement pour les runners affectés dans config.toml.
• Pour les registres avec certificats auto-signés, faites confiance à l'AC sur l'hôte.

Retour en arrière : Supprimez les entrées d'environnement proxy si elles brisent la connectivité interne.

6. Échecs de tirage d'image avec l'exécuteur Docker (exemple construit)

Symptômes : error response from daemon: pull access denied

Vérifications :

• Statut docker login et portée des identifiants
• Proxy interférant avec docker pull

Étapes de récupération :

• docker login REGISTRY_URL avec un compte robot en lecture seule.
• Si AC privée, installez-la dans le magasin de confiance du moteur Docker et redémarrez le moteur.

Retour en arrière : Revenez à l'étiquette d'image de base précédemment fonctionnelle pour réduire les pièces mobiles.

7. Problèmes de cycle de vie des pods avec l'exécuteur Kubernetes (exemple construit)

Symptômes : pods Pending ou ImagePullBackOff

Vérifications :

• kubectl get events -n runner-namespace
• RBAC : kubectl auth can-i create pods ...
• ImagePullSecrets présent sur le ServiceAccount du runner

Étapes de récupération :

• Accordez le RBAC minimal pour pods, secrets (lecture si nécessaire) et événements.
• Attachez le bon imagePullSecret au ServiceAccount.

Retour en arrière : Réduisez les répliques du runner à 0, annulez les récents changements RBAC, et remontez après validation.

8. Permissions et propriété du système de fichiers

Symptômes : permission refusée pour créer le répertoire de cache ou d'artefacts

Vérifications :

• id gitlab-runner, ls -l répertoires cibles
• SELinux en mode enforcing bloque (Linux) :

  getenforce
  ausearch -m avc -ts recent

Étapes de récupération :

• chown les répertoires à l'utilisateur gitlab-runner.
• Pour SELinux, définissez les contextes appropriés (exemple construit) :

  sudo chcon -Rt svirt_sandbox_file_t /var/lib/gitlab-runner

Préférez les ajustements de politique permanents via semanage fcontext si disponible.

Retour en arrière : Annulez les changements de propriété ou de contexte s'ils affectent d'autres services ; restaurez depuis la sauvegarde de config au besoin.

Liste de contrôle des opérations

Utilisez cette liste concise pour les opérations continues et la réponse rapide aux incidents.

Vérifications rapides quotidiennes ou pré-déploiement

• Confirmez le statut en ligne du runner dans GitLab et notez la profondeur de file.
• systemctl status gitlab-runner montre en cours d'exécution ; pas de boucles de plantage récentes.
• Espace disque au-dessus d'un seuil sûr (exemple construit : > 20 %).

Quand un job bloque ou échoue de façon inattendue

• Capturez le contexte : ID du job, nom du runner, exécuteur, changements récents.
• Vérifiez les étiquettes et les réglages de concurrence.
• Inspectez les 200 dernières lignes de journal : journalctl -u gitlab-runner -n 200 --no-pager.
• Ré-exécutez un seul job avec variables minimales pour isoler.

Gestion des changements

• Sauvegardez config.toml avec horodatage.
• Modifiez une seule variable à la fois ; enregistrez le résultat attendu.
• Redémarrez le runner et vérifiez dans les 5 minutes.
• Si le résultat diverge, revenez immédiatement en arrière en utilisant la sauvegarde.

Hygiène réseau et identifiants

• Validez la résolution DNS et les variables d'environnement proxy pour les utilisateurs runner.
• Faites tourner les identifiants selon un calendrier ; testez les nouveaux identifiants avec un seul runner d'abord.

Capacité et performance

• Suivez le temps d'attente moyen des jobs et le taux de succès.
• Augmentez concurrent prudemment (étape par 1) et observez CPU, mémoire et E/S.

Spécifique à l'exécuteur

• Shell : assurez-vous que les outils de construction et shells requis sont installés pour l'utilisateur du runner.
• Docker : vérifiez la santé du moteur, la connexion au registre et la confiance de l'AC.
• Kubernetes : confirmez la capacité des nœuds, le RBAC et les secrets de tirage d'image.

Retour en arrière et récupération

• Gardez au moins un runner connu bon intact pendant les changements majeurs.
• Maintenez un playbook pour ré-enregistrer un runner avec les bonnes étiquettes et exécuteurs.
• Si un changement cause des échecs généralisés, restaurez config.toml depuis la sauvegarde et redémarrez.

Conclusion

Le dépannage de GitLab Runner devient prévisible lorsque vous commencez avec un inventaire clair, faites un petit changement à la fois et vérifiez chaque étape par rapport aux résultats attendus. Utilisez le chemin de configuration sécurisé, appuyez-vous sur les journaux ciblés et les vérifications de santé, et privilégiez les changements réversibles. Le tableau symptôme-action et la liste de contrôle des opérations vous donnent des chemins rapides vers les corrections courantes et des retours en arrière sûrs. En traitant chaque changement comme une expérience avec un plan de retour en arrière, vous réduisez le rayon d'impact des erreurs et bâtissez la confiance que votre pipeline CI/CD restera fiable sous pression.

Prochaines étapes construites

• Choisissez un runner et exécutez la section Vérification et diagnostics de bout en bout. Limitez à 20 minutes et consignez les constatations.
• Appliquez une amélioration de la section Modes de défaillance et récupération qui traite votre symptôme principal.
• Surveillez pendant un jour : profondeur de file, taux de succès des jobs et latence moyenne de démarrage. Si stable ou amélioré, propagez aux runners additionnels graduellement.

Des étapes ciblées et mesurables rendent le dépannage plus rapide et plus sûr. Commencez étroit, vérifiez localement, puis élargissez avec confiance.