Erreurs de configuration GitLab CI/CD : guide pratique de dépannage

Introduction

GitLab CI/CD est un outil puissant pour automatiser la livraison de logiciels, mais sa configuration peut être à double tranchant. Un simple mot-clé mal placé, une variable incorrecte ou une règle mal comprise peut casser votre pipeline, faire perdre du temps aux développeurs et retarder les mises en production. Beaucoup d'équipes apprennent ces leçons à leurs dépens, souvent après un incident de production ou un déploiement raté. Ce guide vise à court-circuiter cette douleur en cataloguant les erreurs de configuration GitLab CI/CD les plus courantes, en fournissant des exemples pratiques et en expliquant comment valider les changements, revenir en arrière en toute sécurité et dépanner efficacement.

Que vous soyez un développeur novice avec GitLab CI/CD, un consultant DevOps aidant plusieurs clients ou une équipe de startup technique construisant vos premiers pipelines, cet article vous donnera des étapes concrètes pour éviter les pièges et récupérer rapidement lorsque quelque chose tourne mal. Nous nous concentrerons sur des scénarios du monde réel, pas sur la théorie. À la fin, vous aurez une liste de contrôle pour examiner vos propres configurations et un ensemble de commandes pour diagnostiquer les problèmes dans n'importe quel environnement GitLab.

Inventaire des versions et de l'environnement

Avant de plonger dans les erreurs, il est essentiel de savoir exactement avec quoi vous travaillez. Le comportement de GitLab CI/CD peut varier selon les versions, les runners et les exécuteurs. Une configuration qui fonctionne sur GitLab.com peut échouer sur une instance auto-hébergée en raison de fonctionnalités manquantes ou de valeurs par défaut différentes. Par conséquent, la première étape du dépannage de tout problème de pipeline est d'établir un inventaire clair de votre environnement.

Vérifiez votre version de GitLab

La version de GitLab détermine les fonctionnalités CI/CD disponibles. Par exemple, le mot-clé rules a été introduit dans GitLab 12.3, et workflow: rules dans la 12.5. Si vous êtes sur une version plus ancienne, ces constructions provoqueront une erreur de syntaxe. Pour vérifier votre version de GitLab, accédez à la page d'aide (par exemple, https://gitlab.example.com/help) ou exécutez la commande suivante sur le serveur si vous avez un accès SSH :

sudo gitlab-rake gitlab:env:info

Cette commande produit un résumé incluant la version de GitLab, par exemple :

GitLab version: 15.11.0

Notez cette version car certaines fonctionnalités et syntaxes dépendent de la version. Par exemple, parallel: matrix a été introduit dans GitLab 13.3, et l'utiliser sur une version antérieure provoquera une erreur « unknown keyword ».

Versions des runners et exécuteurs

Les runners exécutent les tâches définies dans votre .gitlab-ci.yml. Ils existent en différents types (partagés, de groupe, de projet) et peuvent utiliser divers exécuteurs (shell, Docker, Kubernetes, etc.). L'exécuteur affecte la façon dont les commandes s'exécutent et l'environnement disponible. Pour lister les runners enregistrés pour un projet, utilisez l'API GitLab ou l'interface utilisateur. Avec un jeton d'accès personnel, vous pouvez exécuter :

curl --header "PRIVATE-TOKEN: <votre_jeton>" "https://gitlab.example.com/api/v4/projects/<id_du_projet>/runners"

La réponse est un tableau JSON avec les détails des runners incluant id, description, active, runner_type et ip_address. Notez les tags des runners car ils contrôlent le routage des tâches. Une erreur courante est d'attribuer à une tâche un tag qu'aucun runner ne possède. Par exemple, si votre tâche a tags: [docker] mais que tous les runners sont taggés shell, la tâche restera indéfiniment en attente.

Pour vérifier la version du runner, vous pouvez exécuter :

gitlab-runner --version

Elle doit correspondre ou être compatible avec votre version de GitLab. GitLab maintient un tableau de compatibilité des versions de runner ; utiliser un runner trop ancien peut provoquer des échecs de tâches en raison de fonctionnalités manquantes.

Comprenez votre topologie

Comprenez où vos runners sont hébergés. Sont-ils sur le même réseau que votre serveur GitLab ? Ont-ils accès aux services externes comme les registres de paquets ou les cibles de déploiement ? Les problèmes réseau se manifestent souvent par des échecs de pipeline avec des délais d'attente ou des erreurs « connection refused ». Documentez le chemin réseau attendu pour chaque tâche. Par exemple, une tâche qui déploie vers AWS a besoin d'un accès Internet sortant et de credentials IAM appropriés ; si le runner est dans un sous-réseau restreint, la tâche échouera.

Prérequis

Avant de modifier toute configuration, assurez-vous de disposer des éléments suivants :

• Accès au dépôt du projet et capacité à pousser des modifications sur une branche.
• Permission de consulter les journaux de pipeline et l'état des runners.
• Un clone local du dépôt pour des modifications et validations rapides.
• Connaissance de l'environnement de déploiement (serveurs, comptes cloud, etc.).

Avec cet inventaire, vous pouvez procéder à l'examen de votre configuration en toute confiance.

Chemin de configuration sécurisé

Lorsque vous identifiez une erreur ou souhaitez introduire une nouvelle fonctionnalité CI/CD, résistez à l'envie de faire des changements radicaux directement sur la branche principale. Suivez plutôt un chemin de configuration sécurisé qui minimise les risques et permet un retour en arrière rapide.

Commencez petit et délimité

Le premier pilote utile doit être étroit, mesurable et facile à inspecter localement avant le déploiement. Pour GitLab CI/CD, cela signifie faire un changement à la fois dans une branche de fonctionnalité et le tester isolément. Par exemple, si vous devez ajouter une tâche de déploiement, ajoutez d'abord une simple commande echo pour vous assurer que la tâche s'exécute dans le bon environnement. Ce n'est qu'après que cela fonctionne que vous ajoutez la logique de déploiement réelle.

Utilisez le développement par branches

Créez une branche pour vos changements CI/CD et ouvrez une demande de fusion. Cela vous permet de réviser la différence de configuration et d'exécuter le pipeline dans le contexte de cette branche. GitLab exécutera automatiquement le pipeline pour la branche si le CI est activé. Vous pouvez voir l'état du pipeline directement dans la demande de fusion, ce qui aide à détecter les erreurs avant la fusion. Par mesure de sécurité supplémentaire, vous pouvez configurer la demande de fusion pour exiger un pipeline réussi avant la fusion :

# Dans les paramètres de votre projet, sous Demandes de fusion -> Les pipelines doivent réussir

Cela empêche les fusions accidentelles de configurations cassées.

Validez la syntaxe avant de pousser

Une erreur courante est de pousser un .gitlab-ci.yml avec un YAML invalide ou des mots-clés inconnus. GitLab fera échouer le pipeline immédiatement, mais vous pouvez détecter ces erreurs localement avant même de pousser. GitLab fournit un outil CI Lint dans l'interface sous CI/CD > Pipelines > CI Lint. Cependant, pour une validation locale, vous pouvez utiliser la commande gitlab-ci-lint si vous avez la CLI GitLab (glab) installée :

glab ci lint

Si vous n'utilisez pas glab, vous pouvez utiliser un analyseur YAML générique comme yamllint pour au moins vérifier la syntaxe, bien qu'il ne comprenne pas les mots-clés spécifiques à GitLab. Mieux encore, installez l'extension GitLab Workflow pour VS Code ou utilisez l'outil de lint en ligne. De plus, vous pouvez ajouter un hook de pré-commit pour exécuter glab ci lint automatiquement avant chaque commit.

Utilisez rules et workflow avec précaution

De nombreuses erreurs de configuration proviennent d'une mauvaise compréhension du mot-clé rules et de l'interaction entre only/except (obsolètes) et rules. Un chemin sûr consiste à définir un workflow global qui contrôle quand les pipelines sont créés, puis à utiliser rules sur les tâches individuelles pour un contrôle plus fin. Par exemple :

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_TAG'

Cela garantit que les pipelines ne sont créés que pour les demandes de fusion, les commits sur la branche main et les tags. Sans workflow, vous pourriez obtenir des pipelines en double ou des pipelines pour des événements non désirés. Notez que only et except sont obsolètes et pourraient être supprimés dans les futures versions de GitLab ; migrez vers rules dès que possible.

Changements incrémentaux avec commentaires

Ajoutez toujours des commentaires expliquant pourquoi un changement a été fait. Cela aide les futurs mainteneurs à comprendre le contexte et peut les empêcher d'annuler une correction qui traitait d'un problème subtil. De plus, envisagez d'utiliser le mot-clé extends pour réutiliser des définitions de tâches communes, réduisant la duplication et le risque de configurations incohérentes. Par exemple :

.deploy_template: &deploy_template
  stage: deploy
  script:
    - echo "Deploying..."
  only:
    - main

deploy_production:
  extends: .deploy_template
  environment: production

Exemple de changement sûr

Supposons que vous deviez ajouter une étape de test qui exécute des tests unitaires. Au lieu de l'ajouter directement à main, créez une branche add-test-stage et modifiez .gitlab-ci.yml comme suit :

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script: echo "Building..."

test_job:
  stage: test
  script: echo "Running tests..."

Poussez la branche et observez le pipeline. En cas de succès, ouvrez une demande de fusion. Ce changement isolé garantit que si quelque chose tourne mal, vous pouvez simplement supprimer la branche et recommencer sans affecter le pipeline principal.

Vérification et diagnostics

Après avoir effectué des modifications, vous devez vérifier que la configuration fonctionne comme prévu. Cela implique de vérifier l'état du pipeline, d'examiner les journaux de tâches et éventuellement d'exécuter des commandes sur le runner pour diagnostiquer les problèmes.

État du pipeline et journaux de tâches

Le premier endroit à regarder est la page du pipeline dans GitLab. Un pipeline peut avoir les états : passed, failed, pending, running, canceled ou skipped. Cliquez sur une tâche échouée pour voir son journal. Les erreurs courantes incluent des échecs de commandes shell, des dépendances manquantes ou des problèmes de permission. Le journal montre la commande exacte qui a échoué et le code de sortie. Par exemple, un npm install échoué affichera un résultat comme :

npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/undefined
npm ERR! A complete log of this run can be found in:

Cela indique un problème de dépendance.

Utilisation de gitlab-runner pour le débogage local

Si une tâche échoue en raison de problèmes d'environnement sur le runner, vous pouvez utiliser la commande gitlab-runner pour exécuter une tâche localement à des fins de débogage. Par exemple, si vous avez un runner avec l'exécuteur shell, vous pouvez simuler l'environnement de la tâche en exécutant :

gitlab-runner exec shell test_job

Cela exécutera le script test_job localement en utilisant le même environnement que le runner, ce qui peut révéler des paquets manquants ou des chemins incorrects. Notez que gitlab-runner exec ne fonctionne que pour shell, docker et quelques autres exécuteurs, et il peut ne pas reproduire exactement l'environnement CI, mais il est très utile pour des vérifications rapides.

Vérification de la syntaxe de configuration

Comme mentionné précédemment, utilisez glab ci lint pour valider votre .gitlab-ci.yml. La sortie indiquera si la syntaxe est valide et peut montrer une liste de tâches avec leurs étapes et scripts. Par exemple :

Valid!
- build_job (stage: build)
- test_job (stage: test)

S'il y a une erreur, elle pointera vers la ligne et fournira une indication. Vous pouvez également utiliser l'API pour le lint sans CLI :

curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "stages: [build, test]\nbuild_job:\n  stage: build\n  script: echo Building"}'

L'API renvoie une réponse JSON avec status et errors.

Vérification de la disponibilité des runners

Une tâche bloquée à l'état pending signifie souvent qu'aucun runner n'est disponible pour la prendre en charge. Utilisez l'interface GitLab pour voir quels runners sont actifs et leurs tags. Vous pouvez également utiliser l'API :

curl --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/projects/<id_du_projet>/runners?scope=active"

Si aucun runner n'apparaît, vous devez en enregistrer un ou ajuster les tags de la tâche. Vérifiez également si le runner est en pause ou s'il y a des limites de runner (par exemple, nombre maximal de tâches par runner).

Diagnostic avec les variables

Parfois, une tâche se comporte différemment en raison d'une variable définie au niveau du projet ou du groupe. Pour inspecter les variables disponibles pour une tâche, ajoutez une tâche temporaire qui les affiche (mais faites attention à ne pas exposer de secrets). Par exemple :

debug_vars:
  stage: test
  script:
    - env | sort

Exécutez cette tâche et vérifiez le journal pour des valeurs inattendues. N'oubliez pas de supprimer cette tâche de débogage avant de fusionner pour éviter de divulguer des informations sensibles. Vous pouvez également utiliser echo $VARIABLE_NAME pour des variables spécifiques, mais évitez d'imprimer des secrets comme des mots de passe ou des jetons.

Résultats attendus pour les vérifications courantes

• glab ci lint renvoie Valid! sans erreurs.
• gitlab-runner exec se termine avec le code de sortie 0 et la sortie attendue.
• L'état du pipeline est passed et toutes les tâches montrent des coches vertes.
• Aucune tâche ne reste en pending plus de quelques minutes.

Modes d'échec et récupération

Malgré une configuration soignée, les choses peuvent mal tourner. Il est crucial de comprendre les modes d'échec courants et d'avoir un plan pour récupérer rapidement.

Erreurs de configuration courantes et leurs symptômes

Voici les erreurs les plus fréquentes commises par les équipes, avec des détails sur pourquoi elles surviennent et comment récupérer :

1. Erreurs de syntaxe YAML

Symptôme : Le pipeline échoue immédiatement avec un message comme jobs config should contain at least one visible job ou YAML syntax error.

Pourquoi cela arrive : Souvent, l'indentation est incorrecte ou un caractère spécial n'est pas entre guillemets. YAML est sensible aux espaces, donc un espace manquant peut casser tout le fichier.

Récupération : Utilisez glab ci lint pour identifier la ligne avec l'erreur. Corrigez l'indentation ou les guillemets, puis commitez à nouveau.

2. Mots-clés invalides

Symptôme : Message d'erreur comme unknown keyword: workflow ou jobs:build:rules:rule if invalid expression.

Pourquoi cela arrive : Utilisation d'un mot-clé non pris en charge par votre version de GitLab. Par exemple, utiliser workflow: rules dans GitLab 11.x.

Récupération : Vérifiez votre version de GitLab (comme décrit précédemment). Si le mot-clé est trop récent, mettez à niveau GitLab ou évitez ce mot-clé. Si vous devez prendre en charge des versions plus anciennes, utilisez des inclusions conditionnelles basées sur la version, mais cela ajoute de la complexité.

3. Logique rules incorrecte

Symptôme : Une tâche qui devrait s'exécuter sur la branche main ne s'exécute pas, et le pipeline peut ignorer la tâche de manière inattendue. La tâche n'est pas listée dans le pipeline, ou elle montre skipped.

Pourquoi cela arrive : Une condition de règle est trop restrictive ou l'ordre des règles est incorrect. Rappelez-vous que les règles sont évaluées dans l'ordre jusqu'à la première correspondance, donc si une règle générique vient en premier et correspond, les règles spécifiques ultérieures sont ignorées.

Récupération : Revoyez les conditions rules et testez avec différents noms de branche. Utilisez l'outil CI Lint pour simuler la création de pipeline pour une branche ou un tag spécifique.

4. Tags de runner manquants

Symptôme : Une tâche avec tags: [docker] reste en pending pour toujours. Aucun runner ne la prend en charge.

Pourquoi cela arrive : Aucun runner n'a le tag spécifié, ou tous les runners avec ce tag sont inactifs ou occupés.

Récupération : Soit ajoutez un runner avec ce tag (en modifiant la configuration du runner ou en en enregistrant un nouveau), soit supprimez le tag s'il n'est pas nécessaire. Alternativement, changez la tâche pour utiliser un runner disponible.

5. Variables d'environnement non définies

Symptôme : Une tâche échoue parce qu'une variable requise est manquante. Le journal montre une erreur comme undefined variable ou access denied.

Pourquoi cela arrive : La variable n'est pas définie dans les paramètres du projet, du groupe ou de l'instance, ou elle est définie mais non protégée et la tâche s'exécute sur une branche protégée.

Récupération : Définissez la variable dans les paramètres CI/CD de GitLab (Paramètres > CI/CD > Variables) ou dans la définition de la tâche en utilisant variables. Assurez-vous que les paramètres de protection de la variable correspondent à la branche.

6. Répertoire de travail incorrect

Symptôme : Les commandes s'exécutent dans un répertoire différent de celui attendu, provoquant des erreurs file not found.

Pourquoi cela arrive : Par défaut, les tâches s'exécutent dans le répertoire du projet, mais des scripts personnalisés peuvent changer de répertoire, ou la tâche peut s'attendre à un emplacement différent.

Récupération : Utilisez cd explicitement dans le script ou définissez working_directory dans la tâche (si vous utilisez un exécuteur personnalisé). Pour les exécuteurs Docker, le défaut est /builds/<namespace>/<projet>, mais il peut être remplacé.

7. Échecs d'installation de dépendances

Symptôme : apt-get install ou bundle install échoue en raison du réseau ou de clés manquantes.

Pourquoi cela arrive : Le runner peut ne pas avoir d'accès Internet, ou le dépôt de paquets est inaccessible. Parfois, des clés GPG manquantes ou des caches obsolètes causent des problèmes.

Récupération : Corrigez la source ou utilisez une image en cache. Utilisez cache dans GitLab CI pour mettre en cache les dépendances entre les builds. Par exemple :

cache:
  paths:
    - vendor/

Cela accélère les builds et réduit la dépendance au réseau.

Stratégies de retour en arrière

Lorsqu'un changement de configuration casse un pipeline, la récupération la plus rapide est d'annuler le changement. Étant donné que vos changements doivent être dans une demande de fusion, vous pouvez simplement annuler la demande de fusion ou pousser un commit d'annulation. Si le changement a été fusionné directement, utilisez git revert pour l'annuler.

git revert <hash-du-commit>
git push origin main

Cela crée un nouveau commit qui annule le changement précédent. Alternativement, si vous avez une version connue comme bonne de .gitlab-ci.yml, vous pouvez la restaurer via git checkout :

git checkout <hash-du-bon-commit> -- .gitlab-ci.yml
git commit -m "Revert .gitlab-ci.yml to known good state"
git push origin main

Vérifications de récupération

Après le retour en arrière, vérifiez que le pipeline revient à un état passant. Consultez le pipeline pour la branche main et assurez-vous que toutes les tâches s'exécutent comme prévu. Surveillez également les prochaines exécutions de pipeline pour confirmer la stabilité.

Prévention des échecs futurs

• Utilisez régulièrement l'outil CI Lint, idéalement dans le cadre de votre processus de pré-commit ou de CI.
• Écrivez des tests pour votre configuration CI si possible (par exemple, en utilisant gitlab-ci-lint dans un hook de pré-commit ou une tâche CI dédiée qui lint le fichier).
• Gardez les configurations modulaires avec extends et include pour réduire la complexité et isoler les changements.
• Documentez tout paramètre non évident dans des commentaires ou un README séparé.

Pièges courants à éviter

Au-delà des erreurs spécifiques ci-dessus, voici des pièges comportementaux et de processus courants qui peuvent miner votre configuration CI/CD :

1. Surcompliquer le pipeline

Beaucoup d'équipes essaient de tout faire dans un seul pipeline, ce qui conduit à un .gitlab-ci.yml massif difficile à maintenir. Pourquoi cela arrive : Manque de modularité et désir d'une source unique de vérité. Comment l'éviter : Divisez les pipelines en étapes et utilisez include pour importer des extraits YAML réutilisables. Envisagez d'utiliser des pipelines enfants ou multi-projets pour les flux de travail complexes.

2. Ignorer les performances du pipeline

Les pipelines lents frustrent les développeurs et réduisent la productivité. Pourquoi cela arrive : Ne pas mettre en cache les dépendances, utiliser des images Docker inefficaces ou exécuter des tâches inutiles. Comment l'éviter : Utilisez cache et artifacts pour réutiliser les sorties de build. Profilez la durée du pipeline et optimisez les tâches les plus lentes. Utilisez needs pour exécuter des tâches en parallèle lorsque c'est possible.

3. Sécurité bricolée à la main

Stocker des secrets dans le dépôt ou dans des variables en texte brut est un risque sérieux. Pourquoi cela arrive : Commodité et méconnaissance des fonctionnalités de gestion des secrets de GitLab. Comment l'éviter : Utilisez les variables CI/CD GitLab avec les options « Masked » et « Protected ». Pour des secrets plus avancés, utilisez l'intégration HashiCorp Vault ou les secrets externes de GitLab.

4. Ne pas avoir d'environnement de test pour les changements CI/CD

Appliquer des changements directement aux pipelines de production sans test est risqué. Pourquoi cela arrive : Manque d'un environnement de staging ou de développement pour le CI/CD. Comment l'éviter : Utilisez un projet de test dédié ou une branche séparée avec des tags de runner distincts pour tester les changements avant de fusionner.

5. Oublier de nettoyer

Les vieux artefacts, caches et enregistrements de runners peuvent s'accumuler et causer des problèmes. Pourquoi cela arrive : Pas de plan de maintenance régulier. Comment l'éviter : Planifiez un nettoyage périodique des artefacts et caches (GitLab a des paramètres d'expiration). Supprimez les runners inactifs et les variables inutilisées.

Liste de contrôle opérationnelle

Pour maintenir une configuration GitLab CI/CD saine, suivez cette liste de contrôle reproductible pour les opérations et les revues. Attribuez un propriétaire et une fréquence de revue à chaque élément pour assurer la responsabilité.

Opérations quotidiennes

• Pour chaque demande de fusion, assurez-vous que le pipeline passe avant de fusionner.
• Surveillez la durée du pipeline et optimisez les tâches lentes.
• Conservez les journaux de tâches pour l'audit ; vous pouvez les stocker dans GitLab pour une durée limitée par défaut.

Flux de travail de dépannage

Lorsqu'un pipeline échoue, suivez cette séquence :

1. Regardez le journal de la tâche échouée et notez le message d'erreur.
2. Vérifiez s'il s'agit d'une erreur de syntaxe, d'un problème d'environnement ou d'un échec de script.
3. Si erreur de syntaxe, exécutez glab ci lint pour identifier la ligne.
4. Si problème d'environnement, essayez gitlab-runner exec localement pour reproduire.
5. Si échec de script, examinez la commande et ses dépendances.
6. Corrigez et poussez un nouveau commit sur une branche, puis validez.

Réunion de revue mensuelle

Planifiez une réunion mensuelle de 30 minutes avec le responsable CI/CD, l'administrateur système et un représentant des développeurs pour passer en revue la santé du pipeline, l'utilisation des runners et les changements à venir. Documentez les décisions dans le wiki du projet et attribuez des éléments d'action.

Conclusion

Les erreurs de configuration GitLab CI/CD sont courantes mais évitables. En établissant un inventaire clair de l'environnement, en suivant un chemin de configuration sûr, en vérifiant rigoureusement les changements et en sachant comment récupérer des échecs, vous pouvez maintenir des pipelines robustes. La clé est de traiter la configuration CI/CD comme du code : versionnez-la, révisez-la et testez-la. Utilisez la liste de contrôle fournie pour auditer périodiquement votre configuration et garder une longueur d'avance sur les problèmes potentiels. Avec ces pratiques, votre équipe peut livrer plus rapidement en toute confiance.

Comme dernier conseil, rappelez-vous que l'objectif du CI/CD est d'automatiser les tâches répétitives et de réduire les erreurs humaines, pas d'introduire de nouvelles sources de défaillance. Gardez vos configurations simples, documentées et bien testées. Bonne construction !