## Introduction GitLab CI/CD automatise la livraison de logiciels, mais son architecture peut sembler complexe au premier abord. Les équipes ont souvent du mal à comprendre comment le serveur GitLab, les runners et la configuration du pipeline interagissent, ce qui entraîne un débogage lent et des configurations fragiles. Ce guide décompose cette architecture avec des exemples pratiques. Vous apprendrez les composants essentiels, comment les données et le contrôle circulent dans le système, les points de défaillance courants et les compromis opérationnels. À la fin, vous serez en mesure de concevoir, mettre en œuvre et dépanner des pipelines GitLab CI/CD en toute confiance, en passant d’un pipeline basique à un système d’automatisation robuste et maintenable. Un modèle mental utile consiste à considérer le serveur GitLab comme le coordinateur : il stocke votre code, définit la logique du pipeline et planifie le travail. Les runners sont les travailleurs qui exécutent les jobs. Le fichier .gitlab-ci.yml est le contrat qui indique au serveur quoi faire. Lorsque vous poussez du code, le serveur analyse ce fichier, crée un pipeline avec des étapes et des jobs, puis les runners interrogent le serveur pour obtenir les jobs en attente. Une fois qu’un runner récupère un job, il exécute le script, renvoie les journaux et téléverse les artefacts s’ils sont configurés. Ce flux est central pour tout le reste de ce guide. ## Inventaire des versions et de l’environnement Avant de vous lancer dans GitLab CI/CD, établissez un inventaire clair de votre environnement. Cette section couvre les versions, la topologie et les prérequis nécessaires pour une expérience fluide. ### Instance GitLab Vous avez besoin d’accéder à une instance GitLab, soit GitLab.com (SaaS) soit une installation auto-hébergée. Ce guide suppose GitLab 15.0 ou version ultérieure, bien que les concepts s’appliquent aussi aux versions antérieures. Vérifiez votre version en accédant à https://votre-instance-gitlab/help . La version apparaît en haut de la page. Si vous utilisez une version plus ancienne, certaines fonctionnalités comme rules ou workflow peuvent différer, mais l’architecture de base reste la même. ### Configuration du runner Les jobs GitLab CI/CD sont exécutés par GitLab Runner. Un runner est un processus distinct qui communique avec le serveur GitLab. Vous pouvez installer un runner sur Linux, macOS, Windows ou utiliser Docker. Pour les exemples de ce guide, nous utilisons un runner avec l’exécuteur shell sur Linux, qui exécute les jobs directement sur la machine hôte. Si vous n’avez pas de runner, installez le binaire du runner et enregistrez-le avec la commande suivante : sudo gitlab-runner register Lors de l’enregistrement, vous serez invité à fournir l’URL de l’instance GitLab et un jeton d’enregistrement. Vous pouvez trouver le jeton dans votre projet sous Paramètres > CI/CD > Runners . Pour un test simple, vous pouvez également utiliser un runner partagé fourni par GitLab.com. Les runners partagés sont pratiques mais peuvent avoir des limites de ressources et des temps d’attente. L’exécuteur est l’environnement dans lequel les jobs s’exécutent. Les exécuteurs courants incluent : - Exécuteur shell : exécute les commandes directement sur l’hôte. Simple à configurer mais peut polluer l’hôte et manque d’isolation. - Exécuteur Docker : chaque job s’exécute dans un conteneur neuf. Offre isolation et reproductibilité mais nécessite Docker et peut avoir des démarrages à froid. - Exécuteur Kubernetes : les jobs s’exécutent dans des pods sur un cluster Kubernetes. Évolue bien pour les grandes équipes mais ajoute de la complexité. Le choix de l’exécuteur affecte la sécurité, les performances et la maintenance. Pour une petite équipe ou des projets simples, l’exécuteur shell est souvent suffisant. Pour des configurations plus importantes et multi-projets, Docker ou Kubernetes est préférable. ### Topologie réseau En général, le serveur GitLab et les runners sont sur le même réseau ou peuvent communiquer via HTTPS. Les runners interrogent le serveur pour les jobs, donc le HTTPS sortant (port 443) des runners vers le serveur GitLab doit être autorisé. Le serveur GitLab n’initie pas de connexions vers les runners ; il répond seulement aux requêtes des runners. Si votre runner est derrière un pare-feu ou un NAT, ce modèle d’interrogation fonctionne généralement sans configuration spéciale. Cependant, si le runner ne peut pas joindre le serveur, les jobs ne démarreront jamais. ### Prérequis - Connaissance de base de Git et YAML. - Un projet dans GitLab. - Un runner disponible (partagé ou spécifique au projet). - Facultatif : Docker installé si vous utilisez l’exécuteur Docker. - Accès à l’interface GitLab et, si nécessaire, un jeton d’accès personnel pour les appels API. Exemple de vérification de la connectivité du runner après l’enregistrement : gitlab-runner verify Sortie attendue : Verifying runner... is alive Si le runner n’est pas vivant, vérifiez votre connectivité réseau et les paramètres d’enregistrement. ## Chemin de configuration sûr Lorsque vous débutez avec GitLab CI/CD, il est sage d’implémenter les changements par petites étapes limitées. Cette section fournit un chemin de configuration sûr pour construire un pipeline de manière incrémentale. ### Commencer avec un pipeline minimal Créez un fichier .gitlab-ci.yml à la racine de votre dépôt avec un seul job : stages: - test lint: stage: test script: - echo "Running lint..." - # exemple : exécutez votre commande de lint ici Cela définit une étape nommée test et un job nommé lint . Le job exécute les commandes dans script . Poussez ce fichier vers votre dépôt et vérifiez le pipeline sous CI/CD > Pipelines dans GitLab. Le job devrait réussir. S’il échoue, inspectez les journaux du job pour trouver l’erreur. Les problèmes initiaux courants incluent des erreurs de syntaxe YAML, des étapes manquantes ou des commandes introuvables. ### Ajouter progressivement plus d’étapes Une fois que le pipeline minimal fonctionne, ajoutez d’autres étapes. Par exemple, ajoutez une étape build et une étape deploy : stages: - build - test - deploy build: stage: build script: - echo "Building..." - # ex. : make build test: stage: test script: - echo "Testing..." - # ex. : make test deploy: stage: deploy script: - echo "Deploying..." - # ex. : scp des artefacts vers le serveur environment: name: production Les étapes s’exécutent dans l’ordre indiqué. Les jobs de la même étape s’exécutent en parallèle par défaut. Le mot-clé environment indique à GitLab que ce job déploie vers un environnement spécifique, ce qui active les fonctionnalités de suivi et de retour en arrière. ### Utiliser des variables et des environnements Pour la sécurité, utilisez des variables d’environnement pour les données sensibles. Définissez-les dans GitLab sous Paramètres > CI/CD > Variables . Ensuite, référencez-les dans votre script : deploy: stage: deploy script: - echo "Deploying with key $DEPLOY_KEY" Ne codez jamais en dur des secrets dans votre .gitlab-ci.yml . Les variables GitLab peuvent être masquées et protégées. Les variables masquées sont cachées dans les journaux des jobs, et les variables protégées ne sont disponibles que pour les branches ou tags protégés. Par exemple, pour créer une variable masquée, allez sur la page des variables et cochez l’option « Masquer la variable ». ### Choix d’implémentation limités Au lieu de réécrire tout votre pipeline, limitez les changements à un job ou une étape. Par exemple, pour ajouter la mise en cache, appliquez-la d’abord uniquement au job build : build: stage: build cache: key: "$CI_COMMIT_REF_SLUG" paths: - .m2/repository script: - echo "Building with cache..." Cela met en cache le répertoire .m2/repository (courant pour les builds Maven) en fonction du nom de la branche. Le cache persiste entre les pipelines pour la même branche. Testez ce changement isolément avant de l’étendre à d’autres jobs. Cette approche incrémentale facilite l’identification de ce qui s’est cassé en cas de problème. ## Vérification et diagnostic Après avoir implémenté votre pipeline, vous devez vérifier qu’il fonctionne et diagnostiquer les problèmes. GitLab fournit plusieurs outils pour cela. ### Statut du pipeline et journaux Chaque pipeline a un statut : running , pending , success , failed , canceled ou skipped . Vous pouvez voir le graphe du pipeline et les journaux des jobs depuis l’interface GitLab. Les journaux des jobs sont essentiels pour diagnostiquer les échecs. Vous pouvez aussi utiliser l’API GitLab pour vérifier le statut : curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/pipelines" Remplacez :id par l’identifiant de votre projet et utilisez votre jeton d’accès personnel. Cela renvoie du JSON avec les détails du pipeline, y compris le statut, la référence et le SHA du commit. La sortie attendue inclut un tableau de pipelines avec un champ status pour chacun. Pour récupérer les journaux d’un job spécifique : curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/jobs/:job_id/trace" ### Diagnostic du runner Si des jobs restent bloqués en pending , vérifiez que votre runner est actif : gitlab-runner list Sortie attendue : Listing configured runners Executor=shell Token=xxxx URL=https://gitlab.example.com Vérifiez le statut du runner : sudo gitlab-runner status Si le runner ne tourne pas, démarrez-le : sudo gitlab-runner start Vous pouvez aussi consulter les journaux du runner dans /var/log/gitlab-runner/ sur Linux pour voir les erreurs détaillées. ### Artefacts de job Les artefacts sont des fichiers générés par les jobs qui peuvent être téléchargés ou utilisés par les jobs suivants. Définissez les artefacts dans votre job : build: stage: build script: - echo "build" > build.txt artifacts: paths: - build.txt Après la fin du job, vous pouvez télécharger l’artefact depuis la page du job ou l’utiliser dans des jobs ultérieurs avec dependencies : test: stage: test dependencies: - build script: - cat build.txt Les artefacts peuvent avoir une date d’expiration avec expire_in pour éviter une utilisation illimitée du stockage. ### Débogage avec CI_DEBUG_TRACE Si un job échoue de manière inattendue, activez le traçage de débogage en définissant la variable CI_DEBUG_TRACE=true . Vous pouvez la définir dans l’interface GitLab sous Paramètres > CI/CD > Variables ou lors de la création du pipeline. Cela produit une sortie verbeuse dans les journaux, y compris les variables d’environnement et les détails d’exécution des commandes. Exemple de commande pour lancer un pipeline avec le traçage de débogage : curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/pipeline?ref=main&variables[CI_DEBUG_TRACE]=true" Cela déclenche un nouveau pipeline sur la branche main avec le traçage de débogage activé. La sortie supplémentaire peut être volumineuse, utilisez-la seulement quand c’est nécessaire. ## Modes de défaillance et récupération Comprendre les modes de défaillance courants et comment récupérer est crucial pour maintenir un système CI/CD fiable. Cette section couvre les problèmes typiques et les étapes de récupération. ### Défaillance : le job échoue à cause d’une erreur de commande Cause : Une commande dans script se termine avec un statut non nul. C’est la défaillance la plus courante et elle peut survenir pour de nombreuses raisons, comme une dépendance manquante, une erreur de syntaxe ou un test échoué. Récupération : Vérifiez les journaux du job pour identifier la commande en échec. Le journal montrera la commande et le code de sortie. Corrigez la commande ou ajoutez une gestion d’erreur. Par exemple, si une commande peut échouer mais que vous voulez continuer, vous pouvez utiliser : script: - command_that_may_fail || true Mais utilisez ceci avec parcimonie, car cela peut masquer de vraies erreurs. Une meilleure approche est d’utiliser allow_failure: true sur le job pour laisser le pipeline continuer tout en montrant le job comme échoué ou en avertissement. ### Défaillance : runner hors ligne Cause : Le processus du runner s’est arrêté ou il y a des problèmes réseau. Récupération : Vérifiez le statut du runner : sudo gitlab-runner status S’il ne tourne pas, démarrez-le : sudo gitlab-runner start Vérifiez la connectivité avec gitlab-runner verify . Consultez les journaux du runner dans /var/log/gitlab-runner/ pour des indices. Si le runner tourne mais que les jobs sont en attente, assurez-vous qu’il est activé pour le projet et qu’il a les bons tags. ### Défaillance : échec du téléversement des artefacts Cause : Artefacts volumineux ou problèmes de permission. GitLab a une taille maximale d’artefact (100 Mo par défaut sur GitLab.com). Récupération : Réduisez la taille des artefacts ou ajustez l’expiration des artefacts. Vérifiez les journaux du runner pour les erreurs de téléversement. Vous pouvez augmenter la limite de taille des artefacts dans les paramètres d’administration GitLab (auto-hébergé) ou utiliser artifacts:exclude pour omettre les fichiers inutiles. Pour les très gros artefacts, envisagez un dépôt d’artefacts externe ou un stockage objet. ### Défaillance : pipeline bloqué en attente Cause : Aucun runner disponible avec les tags correspondants, ou le runner n’est pas assigné au projet. Récupération : Vérifiez les tags du job et les tags du runner. Assurez-vous que le runner est activé pour le projet. Vous pouvez exécuter gitlab-runner list pour voir les runners enregistrés. Sur GitLab.com, les runners partagés peuvent être occupés, et les jobs peuvent attendre dans la file. Vous pouvez vérifier la disponibilité du runner en regardant le job en attente et le message « Ce job est bloqué car le projet n’a aucun runner en ligne qui lui est assigné ». ### Contrôles de retour en arrière et de récupération Si un changement de configuration casse le pipeline, revenez à une version précédente connue comme bonne du .gitlab-ci.yml . Utilisez l’historique Git pour revenir en arrière : git revert Après le retour en arrière, poussez et vérifiez que le pipeline réussit. Gardez vos changements de pipeline petits et révisables pour faciliter le retour en arrière. Envisagez d’utiliser l’éditeur de pipeline de GitLab, qui a une vue visuelle et valide la syntaxe avant de commiter. ### Mesures préventives - Utilisez rules pour contrôler quand les jobs s’exécutent. Par exemple, n’exécutez les jobs de déploiement que sur la branche principale. - Utilisez allow_failure: true pour les jobs non critiques comme les rapports de couverture de code. - Définissez des délais d’attente avec timeout pour éviter les jobs bloqués. La valeur par défaut est de 60 minutes, mais vous pouvez définir des valeurs plus courtes ou plus longues par job. - Mettez régulièrement à jour les runners et GitLab pour obtenir les correctifs de sécurité et les nouvelles fonctionnalités. - Surveillez la durée des pipelines et les taux d’échec au fil du temps pour repérer les régressions tôt. ## Pièges courants et comment les éviter Même les équipes expérimentées rencontrent des problèmes récurrents avec GitLab CI/CD. Voici les pièges les plus courants, pourquoi ils surviennent et comment les éviter ou s’en remettre. ### Piège 1 : coder en dur les secrets dans .gitlab-ci.yml Pourquoi cela arrive : Cela semble rapide et facile, surtout dans les petites équipes ou les prototypes. Conséquence : Les secrets sont exposés dans le dépôt, et toute personne ayant un accès en lecture peut les voir. Ils apparaissent aussi dans les journaux. Comment éviter : Utilisez toujours les variables CI/CD de GitLab avec le masquage activé. Pour la production, utilisez un gestionnaire de secrets comme HashiCorp Vault et intégrez-le à GitLab. Analysez régulièrement les dépôts pour détecter les secrets exposés. ### Piège 2 : runners trop permissifs Pourquoi cela arrive : Les équipes configurent des runners avec l’exécuteur shell et les exécutent en tant que root pour éviter les problèmes de permission. Conséquence : Un pipeline malveillant ou bogué peut compromettre la machine hôte. C’est un risque de sécurité sérieux. Comment éviter : Utilisez les exécuteurs Docker ou Kubernetes pour isoler les jobs. Si vous utilisez l’exécuteur shell, exécutez le runner en tant qu’utilisateur non root avec des privilèges minimaux. Utilisez les tags de runner de GitLab pour séparer les jobs sensibles. Révisez les permissions des runners régulièrement, et confiez cette revue trimestrielle au responsable DevOps. ### Piège 3 : ignorer le retour du pipeline Pourquoi cela arrive : Les développeurs voient un pipeline rouge mais fusionnent quand même parce qu’ils sont pressés. Conséquence : Le code cassé entre dans la branche principale, provoquant des échecs pour les autres et dégradant la confiance dans le CI. Comment éviter : Appliquez des branches protégées et exigez des pipelines réussis avant la fusion. Utilisez les approbations de merge request de GitLab et les règles only/except pour empêcher les fusions avec des tests échoués. Définissez une propriété claire : le chef d’équipe est responsable de la métrique de santé du pipeline et la revoit chaque semaine. ### Piège 4 : pipelines monolithiques sans cache ni artefacts Pourquoi cela arrive : Au début, le pipeline est petit, et la mise en cache semble inutile. Conséquence : À mesure que le projet grandit, le temps d’exécution explose, et les développeurs perdent du temps à attendre. Comment éviter : Ajoutez la mise en cache pour les dépendances tôt. Divisez les pipelines en étapes et utilisez needs pour les jobs parallèles. Utilisez les artefacts pour transmettre les sorties de build entre les étapes. Révisez les performances du pipeline mensuellement pour identifier les goulots d’étranglement. ### Piège 5 : ne pas utiliser correctement les environnements Pourquoi cela arrive : Les équipes déploient avec des commandes SSH brutes et n’informent pas GitLab des environnements. Conséquence : Vous perdez la visibilité sur ce qui est déployé où, et les retours en arrière sont manuels et sujets aux erreurs. Comment éviter : Définissez les environnements dans vos jobs de déploiement avec environment: name: production . Utilisez le tableau de bord des environnements de GitLab pour voir l’historique des déploiements. Configurez deployments pour pouvoir revenir en arrière en un clic. Le responsable des mises en production doit être propriétaire de la visibilité des déploiements et la revoir après chaque mise en production. ## Liste de contrôle opérationnelle Utilisez cette liste de contrôle pour assurer le bon fonctionnement de votre système GitLab CI/CD. Elle couvre les revues périodiques et les actions immédiates. Chaque élément a un propriétaire et une fréquence de revue pour garantir la responsabilité. ### Vérifications quotidiennes/hebdomadaires
VérificationPropriétaireFréquence
Surveiller les taux de réussite des pipelines. Si le taux descend sous 90 %, enquêtez.Ingénieur CI/CD (ex. : Jordan Lee)Quotidien
Vérifier la santé du runner sur chaque runner : sudo gitlab-runner statusIngénieur DevOps (ex. : Taylor Smith)Quotidien
Examiner les jobs échoués et traiter les problèmes récurrentsChef d’équipe (ex. : Priya Shah)Hebdomadaire le lundi
Examiner les temps d’attente des runners. Si les jobs attendent plus de 5 minutes, ajoutez des runners.Ingénieur CI/CD (Jordan Lee)Hebdomadaire
### Avant les changements majeurs - [ ] Sauvegarder le .gitlab-ci.yml et les scripts pertinents. Propriétaire : mainteneur du dépôt (ex. : Alex Chen). - [ ] Tester les changements dans une branche ou un projet de test séparé. Propriétaire : développeur effectuant le changement. - [ ] Communiquer avec l’équipe sur les perturbations potentielles du pipeline. Propriétaire : chef d’équipe (Priya Shah). - [ ] Examiner le chemin de mise à niveau de GitLab ou du runner pour la compatibilité. Propriétaire : ingénieur DevOps (Taylor Smith). ### Après les changements - [ ] Vérifier que le pipeline s’exécute de bout en bout sur la branche par défaut. Propriétaire : développeur. - [ ] Vérifier que les artefacts sont générés correctement et peuvent être téléchargés. Propriétaire : ingénieur QA (ex. : Casey Jones). - [ ] Surveiller l’augmentation des temps d’attente ou de l’utilisation des ressources. Propriétaire : ingénieur CI/CD (Jordan Lee). - [ ] Mettre à jour toute documentation sur la configuration du pipeline. Propriétaire : développeur. ### Sécurité - [ ] Faire tourner les variables CI/CD (jetons, clés) périodiquement, au moins tous les 90 jours. Propriétaire : agent de sécurité (ex. : Robin Patel). - [ ] Limiter l’accès aux branches et environnements protégés. Propriétaire : administrateur du dépôt (Alex Chen). - [ ] Examiner les permissions des runners : s’assurer que les runners ne sont pas trop privilégiés. Propriétaire : ingénieur DevOps (Taylor Smith), revue mensuelle. - [ ] Activer la journalisation d’audit pour les événements de pipeline. Propriétaire : agent de sécurité (Robin Patel). ### Performance - [ ] Optimiser la durée du pipeline en mettant en cache les dépendances. Propriétaire : développeur. - [ ] Utiliser des jobs parallèles lorsque c’est possible avec needs ou parallel . Propriétaire : développeur. - [ ] Nettoyer les anciens artefacts et journaux. Utilisez expire_in sur les artefacts et planifiez un job de nettoyage. Propriétaire : ingénieur CI/CD (Jordan Lee), hebdomadaire. - [ ] Examiner la capacité des runners et envisager l’autoscaling si vous utilisez Docker. Propriétaire : ingénieur DevOps (Taylor Smith), mensuel. Exemple de commande pour nettoyer les anciens pipelines via l’API (à utiliser avec prudence) : curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/pipelines?status=success&before=2023-01-01" Cela supprime les pipelines réussis avant une date spécifique. Confirmez la disponibilité de l’API dans votre version et testez d’abord sur un projet non critique. Le propriétaire de cette action est l’ingénieur CI/CD. ## Conclusion Dans ce guide, nous avons exploré l’architecture de GitLab CI/CD avec des exemples pratiques. Vous avez appris les composants essentiels : le serveur GitLab, les runners et la configuration du pipeline. Nous avons parcouru un chemin de configuration sûr, des techniques de vérification et des modes de défaillance courants avec des étapes de récupération. La liste de contrôle opérationnelle vous aidera à maintenir un système CI/CD sain. Prochaines étapes pour consolider vos connaissances : - Configurez un pipeline minimal dans un projet de test. - Expérimentez avec différents exécuteurs (shell, Docker, Kubernetes) pour comprendre les compromis. - Implémentez la mise en cache et les artefacts pour optimiser votre pipeline. - Explorez les fonctionnalités avancées comme les environnements, les releases et les review apps. - Documentez votre architecture de pipeline et partagez-la avec votre équipe. Rappelez-vous, GitLab CI/CD est un outil flexible. Commencez petit, itérez et améliorez continuellement votre automatisation. La clé est de comprendre le flux de contrôle et de données, afin de concevoir des pipelines résilients qui accélèrent votre processus de développement. Attribuez une propriété claire pour la santé et la sécurité du pipeline, et révisez régulièrement votre configuration. Avec un modèle mental solide et une attention aux détails opérationnels, vous pouvez éviter les pièges courants et garder votre processus de livraison rapide et fiable.