Dépannage CI/CD GitLab : guide pratique de diagnostic et de récupération

Introduction

Les pipelines CI/CD GitLab automatisent le chemin depuis le commit de code jusqu'au déploiement, mais lorsqu'un pipeline échoue, les messages d'erreur peuvent être cryptiques et la cause racine difficile à trouver. Que vous soyez un développeur poussant du code, un consultant DevOps gérant plusieurs projets, ou une équipe de startup technique construisant votre premier workflow CI/CD, des compétences systématiques de dépannage sont essentielles. Ce guide fournit des méthodes pratiques et concrètes pour diagnostiquer et résoudre les échecs courants de CI/CD GitLab. Nous couvrirons l'inventaire de l'environnement, les modifications de configuration sûres, les commandes de vérification, les modes de défaillance et la récupération, une liste de contrôle opérationnelle et les pièges courants. À la fin, vous serez en mesure d'aborder les problèmes de pipeline avec confiance, de minimiser les temps d'arrêt et de mettre en œuvre des correctifs robustes.

Inventaire de la version et de l'environnement

Avant d'apporter des modifications, établissez une base claire de votre environnement GitLab. Cela évite les erreurs de diagnostic et garantit que vous travaillez avec les versions et composants corrects. Documentez toutes les conclusions dans un emplacement partagé tel que le wiki du projet ou un document d'exploitation dédié.

1.1 Recueillir les informations de l'instance GitLab

Commencez par identifier la version et l'édition de votre instance GitLab. Ces informations sont disponibles dans la zone d'administration ou via l'API. Pour les instances auto-gérées, la zone d'administration se trouve dans Zone d'administration > Vue d'ensemble > Tableau de bord. Sur GitLab.com, utilisez le point de terminaison de l'API.

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/version"

Sortie attendue :

{ "version": "16.7.0-ee", "revision": "abc1234" }

Notez si vous utilisez GitLab.com ou une instance auto-gérée. Les instances auto-gérées offrent plus de contrôle mais nécessitent de gérer les mises à niveau et l'infrastructure des runners. Enregistrez également l'URL de l'instance, la méthode d'authentification (SSO, LDAP, intégrée) et les éventuels paramètres de proxy. Par exemple, si votre entreprise utilise un proxy interne, notez son adresse et son port car cela affectera le dépannage réseau.

1.2 Identifier les versions des GitLab Runners

Les runners exécutent les jobs. Listez tous les runners et leurs statuts en exécutant la commande suivante sur chaque hôte de runner :

gitlab-runner list

Exemple de sortie :

Runtime platform arch=amd64 os=linux pid=1234 revision=abcdef12 version=16.7.0 Listing configured runners ConfigFile=/etc/gitlab-runner/config.toml my-runner Executor=docker Token=xxxxxx URL=https://gitlab.example.com

Pour chaque runner, vérifiez son type d'exécuteur (shell, docker, kubernetes, etc.) car les étapes de dépannage diffèrent. Utilisez gitlab-runner verify pour vérifier l'enregistrement :

gitlab-runner verify

Sortie attendue :

Runtime platform arch=amd64 os=linux pid=1234 revision=abcdef12 version=16.7.0 Running in system-mode.

Verifying runner... is alive runner=xxxxxx

Notez les tags du runner, qui déterminent les jobs qu'il peut récupérer. Par exemple, un runner avec le tag docker n'exécutera que les jobs qui spécifient ce tag. Enregistrez également le paramètre de concurrence du runner et les ressources disponibles (CPU, mémoire, disque) car elles affectent les performances des jobs.

Pour voir tous les runners enregistrés sur votre instance GitLab, utilisez l'API admin :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/runners/all"

Cela renvoie un tableau JSON avec l'identifiant, la description, le statut, les tags de chaque runner, et plus encore. Enregistrez cette sortie pour référence.

1.3 Documenter la topologie du pipeline

Cartographiez les étapes et les jobs de votre pipeline. Listez les étapes définies dans .gitlab-ci.yml et identifiez les dépendances externes telles que les dépôts d'artefacts, les cibles de déploiement ou les services externes. Créez un diagramme simple à l'aide d'un outil comme Mermaid ou draw.io. Pour chaque étape, notez ce qui suit :

• Les tags de runner requis.
• Les variables d'environnement ou secrets utilisés.
• Les services externes accédés (par exemple, registre npm, registre Docker, AWS S3).
• La durée attendue et la criticité.

Exemple de topologie pour une application web :

Cet inventaire aide à tracer les échecs entre les étapes. Par exemple, si le job deploy-stg échoue, vous savez vérifier la clé SSH et la disponibilité du serveur de staging.

1.4 Examiner les prérequis

Assurez-vous que les prérequis suivants sont remplis :

• Instance GitLab joignable depuis les machines des runners. Testez avec ping et curl vers l'URL GitLab.
• Le runner dispose des permissions nécessaires (par exemple, pour extraire des images, accéder aux dépôts). Vérifiez le jeton d'enregistrement du runner et les paramètres spécifiques au projet.
• Connectivité réseau vers les services externes (si utilisés). Testez avec nc -zv registry.example.com 443.
• Secrets ou variables requis configurés dans les paramètres CI/CD de GitLab. Listez toutes les variables dans Paramètres du projet > CI/CD > Variables et vérifiez qu'elles sont correctement définies et non expirées.

Documentez tout prérequis manquant et attribuez un responsable pour le résoudre avant de continuer.

Chemin de configuration sûr

Lors de la modification de la configuration du pipeline, adoptez une approche limitée et incrémentale pour minimiser les risques et faciliter le retour en arrière. Toutes les modifications doivent passer par le système de contrôle de version, et vous devez avoir un plan de retour en arrière clair avant tout changement.

2.1 Utiliser les indicateurs de fonctionnalité et la logique conditionnelle

Introduisez les modifications derrière des variables d'environnement ou des règles. Par exemple, pour tester une nouvelle méthode de déploiement sur une branche spécifique, utilisez rules dans .gitlab-ci.yml :

deploy: script: ./deploy.sh rules:

• if: '$CI_COMMIT_BRANCH == "main" && $ENABLE_NEW_DEPLOY == "true"'

Définissez ENABLE_NEW_DEPLOY comme variable dans les paramètres du projet, initialement à "false". Cela permet un retour en arrière rapide en basculant la variable à "false" ou en la supprimant. Le responsable de cette décision est le responsable DevOps (par exemple, Priya Shah, responsable de l'ingénierie), qui examine la variable chaque semaine pour décider de conserver la fonctionnalité ou de la supprimer.

2.2 Conserver les configurations dans le contrôle de version

Toute la configuration du pipeline doit être dans .gitlab-ci.yml stocké dans le dépôt. Utilisez des demandes de fusion pour les modifications et exigez une revue. Cela fournit une piste d'audit naturelle et un retour en arrière par réversion. Par exemple, si une modification casse le pipeline, vous pouvez annuler la demande de fusion en un clic dans l'interface GitLab ou en exécutant git revert <commit-sha>.

2.3 Utiliser les inclusions pour des modifications modulaires

Divisez les grandes configurations en extraits réutilisables à l'aide de include :

include:

• local: '/ci/templates/deploy.yml'

Lors de la modification d'une partie spécifique, ne modifiez que ce fichier, réduisant ainsi l'impact. Conservez les fichiers inclus dans le même dépôt sous un répertoire ci/. Cela facilite également la revue des modifications car le diff est limité à un fichier.

2.4 Tester les modifications dans un environnement sûr

Pour les instances auto-gérées, envisagez d'utiliser une instance GitLab de préproduction ou un projet séparé pour valider les modifications avant de les appliquer à la production. Pour GitLab.com, utilisez une branche séparée et des règles de déclenchement limitées. Par exemple, créez un projet de test qui reflète la configuration CI du projet de production et utilisez-le pour tester de nouvelles configurations de runner ou des modifications de pipeline.

2.5 Exemple : modification limitée d'un job

Supposons que vous deviez mettre à jour une version d'image Docker dans un job. Au lieu de modifier directement le job dans la branche principale, créez une branche de fonctionnalité :

build: image: node:16 script: npm run build

Changez en :

build: image: node:18 script: npm run build

Poussez vers une branche et observez le pipeline. S'il échoue, annulez le commit et poussez à nouveau. Cela limite l'impact à la branche de fonctionnalité et vous permet de tester avant de fusionner vers la branche principale. Le responsable de cette modification est le développeur qui la fait, et le délai de revue attendu est d'un jour ouvrable.

Vérification et diagnostics

Après avoir apporté des modifications, vérifiez que le pipeline se comporte comme prévu. Utilisez les journaux et les commandes de diagnostic pour confirmer. Comparez toujours le nouveau comportement avec la base documentée de la section 1.

3.1 Vérifier le statut du pipeline et les journaux

Utilisez l'interface GitLab pour afficher les journaux du pipeline. Pour un accès en ligne de commande, utilisez l'API :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/:id/pipelines/:pipeline_id/jobs"

La sortie d'exemple inclut les statuts et identifiants des jobs. Pour récupérer le journal d'un job spécifique :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/:id/jobs/:job_id/trace"

La trace est en texte brut, que vous pouvez filtrer pour les erreurs. Par exemple, pour trouver toutes les lignes d'erreur dans un journal de job, enregistrez la trace dans un fichier et exécutez :

grep -i "error" job_trace.log

Cela aide à identifier rapidement la commande en échec.

3.2 Vérifier la connectivité du runner

Sur la machine du runner, testez la connectivité vers GitLab :

gitlab-runner --debug run --config /etc/gitlab-runner/config.toml

Recherchez les messages "Checking for jobs..." et "Received job". Si le runner ne peut pas se connecter, vérifiez le pare-feu réseau et le jeton. Exécutez également un simple curl depuis l'hôte du runner vers l'URL GitLab :

curl -I https://gitlab.example.com

Sortie attendue : HTTP/1.1 302 Found ou 200 OK. Si vous obtenez un délai de connexion, vérifiez les règles DNS et de pare-feu.

3.3 Diagnostiquer les échecs liés à Docker

Pour les exécuteurs Docker, assurez-vous que le runner peut extraire des images. Exécutez un job simple avec docker pull :

docker pull node:18

Sortie attendue :

18: Pulling from library/node Digest: sha256:... Status: Image is up to date for node:18

Si l'extraction échoue, vérifiez l'authentification du registre et la configuration du runner. Pour les registres privés, assurez-vous que le runner a les informations d'identification correctes dans son config.toml ou ses variables d'environnement. Testez manuellement l'authentification :

docker login registry.example.com

Puis extrayez à nouveau. Si l'image est volumineuse, envisagez d'utiliser un miroir local ou un cache.

3.4 Valider la syntaxe du pipeline

Avant de valider, vérifiez la syntaxe de .gitlab-ci.yml à l'aide de l'outil CI Lint de GitLab disponible dans l'interface sous CI/CD > Pipelines > CI Lint, ou via l'API :

curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "job:\n script: echo hello"}'

La sortie attendue inclut "status": "valid" ou des erreurs. Toujours valider le contenu complet du fichier, pas seulement un extrait. Vous pouvez également utiliser l'outil en ligne de commande gitlab-ci-lint s'il est disponible.

3.5 Inspecter les journaux du runner

Les journaux du runner contiennent souvent des messages d'erreur détaillés. L'emplacement dépend de l'installation :

• Systemd : journalctl -u gitlab-runner
• Paquet Linux : /var/log/gitlab-runner/
• Conteneur Docker : docker logs <conteneur>

Exemple :

journalctl -u gitlab-runner -n 50

Recherchez des motifs comme "ERROR: Job failed: execution took longer than", "ERROR: Preparation failed", etc. Ces motifs indiquent des problèmes courants. Par exemple, "execution took longer than" suggère un délai d'attente du job, que vous pouvez augmenter dans la définition du job avec timeout: 2h.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants et comment s'en remettre est crucial pour maintenir la disponibilité. Le tableau suivant résume les modes de défaillance les plus fréquents, leurs symptômes et leurs causes.

4.1 Modes de défaillance courants

4.2 Étapes de retour en arrière et de récupération

Chaque mode de défaillance a une procédure de récupération spécifique. Documentez toujours les commandes exactes exécutées et les résultats dans le journal des incidents.

Scénario 1 : Runner indisponible

• Vérifiez le statut du runner : gitlab-runner status
• S'il est arrêté, démarrez-le : sudo gitlab-runner start
• Si le runner est enregistré mais ne récupère pas de jobs, vérifiez que les tags correspondent aux exigences du job. Vérifiez les tags du job dans .gitlab-ci.yml et les tags du runner dans config.toml.
• S'ils sont mal configurés, modifiez config.toml et redémarrez : sudo gitlab-runner restart.

Exemple : Un job avec le tag docker est en attente car le seul runner en ligne a le tag shell. Corrigez en changeant le tag du job ou en ajoutant un runner avec le bon tag.

Scénario 2 : Échec d'authentification

• Pour le registre Docker, réauthentifiez-vous : docker login registry.example.com
• Pour l'accès au dépôt Git, rajoutez les clés SSH ou les jetons de déploiement.
• Mettez à jour les variables CI/CD dans les paramètres du projet. Vérifiez les jetons expirés et faites-les tourner.

Exemple : Un job échoue à extraire une image privée avec « Échec d'authentification ». La correction consiste à mettre à jour la variable DOCKER_AUTH_CONFIG avec de nouvelles informations d'identification et à relancer.

Scénario 3 : Épuisement des ressources

• Augmentez les ressources du runner ou réduisez les jobs simultanés (concurrent dans config.toml).
• Ajoutez des étapes de nettoyage aux jobs pour libérer de l'espace disque, par exemple rm -rf ~/.cache dans le script.
• Utilisez gitlab-runner cleanup pour supprimer les anciens répertoires de build.
• Surveillez l'utilisation du disque avec df -h et la mémoire avec free -m.

Exemple : Un job échoue avec « out of memory » lors de l'exécution des tests. Augmentez la mémoire du runner ou divisez la suite de tests en jobs parallèles.

Scénario 4 : Erreurs de script

• Relancez le job avec la journalisation de débogage : définissez CI_DEBUG_TRACE=true dans les variables du projet pour obtenir une sortie verbeuse.
• Vérifiez les dépendances manquantes et ajoutez des étapes d'installation. Par exemple, si python est manquant, ajoutez apt-get install python3 ou utilisez une image Docker qui l'inclut.
• Passez en revue le script pour les chemins codés en dur et les hypothèses incorrectes sur l'environnement du runner.

Scénario 5 : Échec de téléversement d'artefacts

• Assurez-vous que artifacts: paths sont correctement spécifiés. Utilisez des chemins absolus ou relatifs au répertoire de build.
• Augmentez la limite de taille des artefacts si nécessaire (paramètre d'administration). La valeur par défaut est de 100 Mo.
• Vérifiez les permissions de stockage. Pour le stockage local, assurez-vous que l'utilisateur GitLab a un accès en écriture au répertoire des artefacts.

4.3 Vérification de la récupération

Après avoir appliqué les correctifs, relancez le pipeline et vérifiez que tous les jobs réussissent. Vérifiez les journaux pour les sorties attendues. Utilisez la liste de contrôle ci-dessous pour confirmer la récupération.

• [ ] Le statut du pipeline est vert.
• [ ] Tous les jobs sont terminés dans les délais prévus.
• [ ] Aucun motif d'erreur dans les journaux des jobs.
• [ ] Les artefacts sont téléversés correctement et peuvent être téléchargés.
• [ ] Le déploiement (le cas échéant) est réussi et l'application est saine.

Le responsable de la récupération (par exemple, l'ingénieur DevOps) doit documenter l'incident et mettre à jour le manuel d'exploitation avec toute nouvelle découverte.

Liste de contrôle des opérations

Utilisez cette liste de contrôle reproductible pour les opérations courantes et le dépannage. Attribuez un responsable unique pour chaque élément de la liste et une fréquence de revue. Le responsable par défaut est le responsable DevOps sauf indication contraire.

Avant les modifications

• [ ] Documenter les versions actuelles de GitLab et des runners. Responsable : responsable DevOps. Fréquence : mensuelle.
• [ ] Noter la topologie du pipeline et les dépendances. Responsable : responsable de projet. Fréquence : trimestrielle ou lors d'un changement majeur.
• [ ] S'assurer que la configuration est dans le contrôle de version. Responsable : tous les développeurs. Fréquence : à chaque commit.
• [ ] Identifier les points de retour en arrière (par exemple, commit précédent, bascule de variable). Responsable : développeur effectuant la modification. Fréquence : par modification.

Pendant les modifications

• [ ] Effectuer des modifications limitées (une modification par demande de fusion). Responsable : développeur. Fréquence : par modification.
• [ ] Utiliser des règles pour limiter l'impact (par exemple, uniquement sur des branches spécifiques). Responsable : responsable DevOps. Fréquence : par modification.
• [ ] Valider la syntaxe de .gitlab-ci.yml. Responsable : développeur. Fréquence : à chaque commit sur le fichier CI.

Après les modifications

• [ ] Surveiller le statut du pipeline. Responsable : développeur. Fréquence : immédiatement après la modification.
• [ ] Vérifier les journaux du runner pour les erreurs. Responsable : ingénieur DevOps. Fréquence : après chaque exécution de pipeline ou quotidiennement.
• [ ] Vérifier les sorties attendues dans les journaux des jobs. Responsable : développeur. Fréquence : après chaque exécution de pipeline.
• [ ] Tester le retour en arrière si nécessaire. Responsable : responsable DevOps. Fréquence : au besoin.

Revue périodique

• [ ] Mettre à jour régulièrement les runners et l'instance GitLab. Responsable : responsable DevOps. Fréquence : mensuelle ou selon la fenêtre de maintenance.
• [ ] Examiner les paramètres et variables CI/CD du projet. Responsable : responsable DevOps. Fréquence : mensuelle.
• [ ] Nettoyer les anciens artefacts et caches. Responsable : ingénieur DevOps. Fréquence : hebdomadaire.
• [ ] Examiner les performances du pipeline et optimiser. Responsable : responsable DevOps. Fréquence : trimestrielle.

Pièges courants et comment les éviter

Même les équipes expérimentées tombent dans des pièges courants lors du dépannage de CI/CD GitLab. Voici les pièges les plus fréquents, pourquoi ils se produisent, et comment les éviter ou s'en remettre.

Piège 1 : Ignorer les tags des runners

Pourquoi cela arrive : Les développeurs supposent que n'importe quel runner peut récupérer un job, mais les jobs avec des tags spécifiques ne s'exécutent que sur des runners avec des tags correspondants. Si un job est bloqué en attente, la première vérification doit être les tags des runners.

Comment l'éviter : Documentez les tags des runners dans le README du projet et dans la topologie du pipeline. Dans .gitlab-ci.yml, utilisez des tags significatifs et minimisez le nombre de tags par runner.

Comment s'en remettre : Exécutez gitlab-runner list pour voir les tags des runners et comparez-les avec les tags du job. Soit modifiez le tag du job, soit ajoutez un runner avec le bon tag.

Piège 2 : Coder en dur des secrets dans .gitlab-ci.yml

Pourquoi cela arrive : Il est pratique de mettre des mots de passe ou des jetons directement dans la configuration, mais cela expose les secrets dans le dépôt et rend la rotation difficile.

Comment l'éviter : Utilisez des variables CI/CD avec masquage et protection. Stockez les secrets dans Paramètres du projet > CI/CD > Variables et référencez-les comme $NOM_DE_VARIABLE. Pour les fichiers sensibles, utilisez des variables de type fichier.

Comment s'en remettre : Si un secret a fuité, révoquez-le immédiatement et faites une rotation. Ensuite, supprimez la valeur codée en dur et remplacez-la par une variable. Analysez l'historique du dépôt pour les fuites et forcez un push d'un historique nettoyé si nécessaire.

Piège 3 : Ne pas utiliser la mise en cache efficacement

Pourquoi cela arrive : Les équipes négligent souvent la mise en cache, ce qui conduit à des pipelines lents et à une charge inutile sur les dépendances externes. Sans cache, chaque job retélécharge les dépendances.

Comment l'éviter : Utilisez cache et artifacts de manière appropriée. Mettez en cache les dépendances comme les modules npm ou les dépôts Maven. Exemple :

cache: paths:

• node_modules/

Comment s'en remettre : Si le pipeline est lent, vérifiez les journaux des jobs pour les téléchargements répétés de dépendances. Ajoutez des sections de cache aux jobs concernés et relancez.

Piège 4 : Négliger les limites de ressources des runners

Pourquoi cela arrive : Les runners peuvent avoir une mémoire ou un disque insuffisants pour les tâches de build, provoquant des échecs intermittents. Cela est courant lorsque les jobs parallèles augmentent l'utilisation des ressources.

Comment l'éviter : Surveillez les métriques de l'hôte du runner avec des outils comme Prometheus ou htop. Définissez des valeurs appropriées pour concurrent et limit dans config.toml. Utilisez des limites de ressources Docker si vous utilisez l'exécuteur Docker.

Comment s'en remettre : Réduisez la concurrence, ajoutez plus de runners, ou augmentez la capacité de l'hôte du runner. Pour l'exécuteur Docker, définissez memory et cpus dans la configuration du runner.

Piège 5 : Négliger les mises à jour des runners

Pourquoi cela arrive : Les équipes exécutent souvent des runners obsolètes, ce qui peut entraîner des problèmes de compatibilité avec les nouvelles fonctionnalités de GitLab et des vulnérabilités de sécurité.

Comment l'éviter : Abonnez-vous aux notes de version de GitLab et planifiez des mises à jour mensuelles des runners. Utilisez la même version pour GitLab et les runners lorsque c'est possible.

Comment s'en remettre : Mettez à jour le runner en utilisant le gestionnaire de paquets : sudo apt-get update && sudo apt-get install gitlab-runner (ou équivalent). Vérifiez avec gitlab-runner --version.

Piège 6 : Ne pas planifier les retours en arrière

Pourquoi cela arrive : Les modifications sont apportées à la hâte sans considérer comment revenir en arrière si quelque chose tourne mal, ce qui entraîne des temps d'arrêt prolongés.

Comment l'éviter : Ayez toujours un plan de retour en arrière avant d'apporter des modifications. Utilisez des indicateurs de fonctionnalité, le contrôle de version et des modifications incrémentales comme décrit dans la section 2. Conservez les versions précédentes de config.toml et .gitlab-ci.yml.

Comment s'en remettre : Si une modification casse le pipeline, annulez immédiatement le commit ou basculez l'indicateur de fonctionnalité. Documentez la procédure de retour en arrière dans le manuel.

Conclusion

Le dépannage des pipelines CI/CD GitLab implique une approche systématique : recueillir les informations sur l'environnement, apporter des modifications de configuration sûres, vérifier avec des contrôles observables et savoir comment se remettre des échecs. En suivant les commandes pratiques et les listes de contrôle de ce guide, vous pouvez réduire les temps d'arrêt et maintenir des processus CI/CD robustes. Commencez par appliquer ces techniques à votre prochaine défaillance de pipeline, et construisez progressivement une bibliothèque de problèmes connus et de solutions pour votre équipe. N'oubliez pas de garder les configurations sous contrôle de version et les modifications incrémentales pour faciliter le retour en arrière. Avec la pratique, vous transformerez le dépannage d'une bousculade réactive en une routine proactive et gérable. Attribuez des responsables clairs pour chaque élément de la liste de contrôle et examinez régulièrement la liste des opérations pour assurer une amélioration continue.