## Intro Exploiter GitLab Runner en production ne se limite pas à installer un binaire et à espérer que les tâches se terminent. Cela exige un flux de travail reproductible et observable, qui passe d'un problème détecté à une résolution vérifiée. Sans liste de contrôle, les opérateurs sautent souvent l'inspection en lecture seule, modifient la configuration à l'aveugle et peinent à récupérer lorsque l'état attendu n'est pas atteint. Cet article fournit une liste de contrôle opérationnelle pratique pour GitLab Runner, destinée aux développeurs, consultants DevOps et équipes techniques de startups qui gèrent une infrastructure CI/CD auto-hébergée. Il relie les domaines opérationnels clés - inventaire des versions et de l'environnement, chemins de configuration sûrs, vérification et diagnostic, modes de défaillance et récupération, et liste de contrôle consolidée des opérations - à des commandes concrètes, des sorties attendues, des signaux de défaillance et des décisions de récupération. Le principe directeur est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier après chaque changement et documenter comment revenir en arrière si l'état attendu n'est pas atteint. Toutes les recommandations sont limitées aux versions GitLab Runner 15.x et 16.x, les versions stables largement déployées, sauf indication contraire. ## Inventaire des versions et de l'environnement Avant de toucher à un réglage, sachez exactement ce que vous exécutez et où. Un inventaire des versions et de l'environnement établit l'état actuel afin que tout changement ultérieur soit informé et réversible. Commencez par identifier la version installée de GitLab Runner et la topologie de déploiement. Exécutez la commande de version en lecture seule sur l'hôte du runner : gitlab-runner --version Exemple de sortie attendue : Version: 16.5.0 Git revision: 8f1ad6c1 Git branch: 16-5-stable GO version: go1.20.7 Built: 2023-09-22T06:12:13+00:00 OS/Arch: linux/amd64 Comparez cette version avec la version de l'instance GitLab que vous utilisez. GitLab Runner suit une politique de compatibilité où le runner devrait idéalement être dans une version mineure du serveur GitLab, ou au moins ne pas être plus ancien que la plus ancienne version de runner prise en charge. Vérifiez la compatibilité dans la documentation GitLab pour votre version spécifique de GitLab. Ensuite, déterminez comment le runner est installé et géré. Utilisez votre gestionnaire de paquets ou systemd pour voir l'état de l'unité : systemctl status gitlab-runner Recherchez la ligne Loaded: pour confirmer l'emplacement du fichier d'unité, et Active: pour voir si le service est en cours d'exécution. Si le runner est déployé en tant que conteneur Docker, inspectez le conteneur : docker ps --filter "name=gitlab-runner" Capturez les détails d'enregistrement du runner sans exposer de secrets. La commande list affiche les runners configurés et leurs exécuteurs : sudo gitlab-runner list Exemple de sortie : Listing configured runners ConfigFile=/etc/gitlab-runner/config.toml my-project-runner Executor=docker Token=glrt-xxxxxx URL=https://gitlab.example.com N'imprimez jamais le jeton complet dans les journaux ou les articles. Traitez toute sortie contenant Token= comme sensible et masquez-la avant de la coller dans des tickets ou de la documentation. Enregistrez la sortie de la commande suivante pour comprendre l'environnement hôte si le runner utilise l'exécuteur shell : uname -a && lscpu | head -n 5 Cela capture le noyau, l'architecture et le modèle de CPU, ce qui peut avoir une importance pour les performances de build et la compatibilité. Créez un petit tableau d'inventaire comme celui ci-dessous et tenez-le à jour :

Attribut	Valeur d'exemple	Commande pour vérifier
Version du runner	16.5.0	`gitlab-runner --version`
Type d'exécuteur	docker	`gitlab-runner list` (regardez la colonne Executor)
Chemin du fichier de config	/etc/gitlab-runner/config.toml	`systemctl status gitlab-runner` (ligne Loaded)
État du service	active (running)	`systemctl status gitlab-runner`
OS hôte et noyau	Ubuntu 22.04, 5.15.0-84-generic	`uname -a` et `cat /etc/os-release`
Version Docker (si utilisée)	24.0.6	`docker --version`

Complétez cet inventaire avant tout changement. Il servira de référence pour le retour en arrière et pour diagnostiquer les problèmes plus tard. ## Chemin de configuration sûr Modifier la configuration de GitLab Runner peut casser tous les builds si cela est fait avec négligence. Le chemin sûr implique de valider la syntaxe, de sauvegarder la configuration actuelle, d'apporter une modification minimale et de recharger le service avec vérification. Le fichier de configuration central est /etc/gitlab-runner/config.toml . Avant de le modifier, créez une sauvegarde horodatée : sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak.$(date +%Y%m%d%H%M%S) Validez ensuite la configuration actuelle en exécutant le runner en mode débogage sans démarrer de tâche : sudo gitlab-runner verify Cette commande charge la configuration et vérifie chaque runner par rapport à l'instance GitLab. Elle n'exécute pas de tâche, ce qui la rend sûre pour la validation. Sortie attendue pour une configuration valide : Verifying runner... is alive Si vous devez apporter une modification, comme augmenter la politique de tirage Docker ou ajuster la concurrence, ouvrez d'abord le fichier de configuration : sudo editor /etc/gitlab-runner/config.toml Apportez un changement ciblé à la fois. Par exemple, pour augmenter la concurrence globale de 1 à 2, localisez le champ concurrent de niveau supérieur et modifiez-le : concurrent = 2 Ne combinez pas de modifications non liées dans une seule édition ; si quelque chose tourne mal, vous devez savoir exactement quel changement en est la cause. Après l'édition, exécutez à nouveau verify . S'il signale une erreur, corrigez-la avant de recharger le service. Ne redémarrez pas le runner tant que la configuration ne passe pas la validation. Pour appliquer le changement, rechargez le service systemd : sudo systemctl reload gitlab-runner Certaines configurations peuvent nécessiter un redémarrage complet au lieu d'un rechargement. Consultez la documentation du service. Après le rechargement, confirmez que le service est actif et que les tâches sont acceptées : systemctl status gitlab-runner sudo gitlab-runner list Si le runner est conteneurisé, le processus diffère. Pour un runner déployé avec Docker, modifiez le fichier de configuration monté sur l'hôte, puis redémarrez le conteneur : docker restart gitlab-runner Conservez toujours le fichier de sauvegarde pendant au moins une semaine. Si un changement provoque des échecs, revenez en arrière en restaurant la sauvegarde et en redémarrant le service : sudo cp /etc/gitlab-runner/config.toml.bak.20231025120000 /etc/gitlab-runner/config.toml sudo systemctl restart gitlab-runner ## Vérification et diagnostic Après tout changement, vérifiez que le runner se comporte correctement sous charge. Le diagnostic aide à isoler les problèmes lorsque les tâches échouent ou se bloquent. Commencez par une seule tâche de test qui sollicite le runner de bout en bout. Créez un .gitlab-ci.yml minimal dans un projet temporaire : test_runner: script: - echo "Runner is working" - gitlab-runner --version Déclenchez le pipeline et observez le journal de la tâche. Une tâche réussie affichera Job succeeded dans la vue du pipeline. Si la tâche n'est pas prise en charge, vérifiez la connexion du runner à GitLab en exécutant : sudo gitlab-runner verify Si la vérification échoue avec une erreur d'authentification, le jeton d'enregistrement a peut-être changé ou été révoqué. Réenregistrez le runner avec un nouveau jeton en dernier recours. Pour un diagnostic plus détaillé, activez temporairement la journalisation de débogage. Modifiez config.toml et définissez le niveau de journalisation : log_level = "debug" Rechargez le runner, exécutez une tâche de test, puis inspectez les journaux : sudo journalctl -u gitlab-runner -f Recherchez les lignes contenant Checking for jobs... et Job succeeded ou des messages d'erreur spécifiques. Désactivez la journalisation de débogage après le dépannage pour éviter la surcharge de journaux. Si les tâches s'exécutent mais échouent, examinez les journaux de tâches dans l'interface GitLab. Les signaux de défaillance courants incluent : - ERROR: Preparation failed: Error response from daemon: ... indiquant un problème de tirage d'image Docker. - ERROR: Job failed: exit code 1 signifiant que le script lui-même a renvoyé une erreur. - ERROR: Failed to remove network for build suggérant un problème de réseau Docker. Vérifiez la santé du démon Docker si l'exécuteur est Docker : docker info La sortie attendue inclut Server Version: et une liste de pilotes de stockage. Si Docker est en mauvaise santé, redémarrez-le : sudo systemctl restart docker Redémarrez ensuite le service du runner pour rétablir les connexions. ## Modes de défaillance et récupération Comprendre les modes de défaillance courants et leurs chemins de récupération est essentiel pour minimiser les temps d'arrêt. Le tableau ci-dessous résume les problèmes fréquents.

Mode de défaillance	Symptôme	Cause probable	Étape de récupération	Vérification
Le runner ne prend pas de tâches	Le pipeline reste en attente, aucun journal de tâche	Runner hors ligne ou non connecté	Vérifiez `systemctl status gitlab-runner`, exécutez `gitlab-runner verify`	Le runner est actif et la vérification réussit
Échec d'authentification	`ERROR: Failed to authorize` dans verify	Jeton invalide ou révoqué	Réenregistrez le runner avec un nouveau jeton	`gitlab-runner verify` réussit, les tâches s'exécutent
Échec de tirage d'image Docker	`ERROR: Preparation failed: image pull failed`	Problème réseau ou nom d'image incorrect	Testez le tirage manuellement : `docker pull <image>`	Le tirage réussit, relancez la tâche
Espace disque plein	Les tâches échouent avec "No space left on device"	Artefacts de build non nettoyés	Exécutez `docker system prune -a --volumes` (avec précaution !)	`df -h` montre de l'espace libéré, les tâches réussissent
Crash du processus runner	Service en échec, les journaux montrent une panique	Bug ou limite de ressources	Redémarrez le service, mettez à niveau la version du runner	Service stable pendant 24 heures
Temps de build lents	Les tâches prennent plus de temps que prévu	Concurrence ou ressources insuffisantes	Augmentez la concurrence dans config.toml, mettez le runner à l'échelle horizontalement	La durée des tâches diminue

Ayez toujours un plan de retour en arrière pour les changements de configuration ou de version. Si une mise à niveau provoque des échecs, rétrogradez vers la version précédente : sudo apt-get install gitlab-runner=16.4.1 Vérifiez ensuite la version : gitlab-runner --version Pour des incidents de production graves, envisagez de basculer vers un runner de secours enregistré sur le même projet si disponible. ## Liste de contrôle des opérations Consolidez ce qui précède dans une liste de contrôle régulière que tout opérateur peut suivre. Effectuez ces tâches à la fréquence indiquée.

Tâche	Fréquence	Responsable	Commande / Action	Résultat attendu
Vérifier la version du runner et la compatibilité	Mensuelle	Ingénieur CI/CD	`gitlab-runner --version` et comparer avec la version GitLab	Version dans la plage prise en charge
Vérifier l'état du service	Quotidienne (automatisée)	Système de surveillance	`systemctl status gitlab-runner`	Actif (en cours d'exécution)
Examiner les journaux du runner pour les erreurs	Hebdomadaire	Ingénieur CI/CD	`journalctl -u gitlab-runner --since "7 days ago"`	Aucune erreur critique
Valider la configuration	Avant tout changement	Ingénieur CI/CD	`gitlab-runner verify`	Tous les runners sont vivants
Sauvegarder le fichier de configuration	Avant tout changement	Ingénieur CI/CD	`cp config.toml config.toml.bak.<horodatage>`	Le fichier de sauvegarde existe
Tester une tâche minimale	Après tout changement	Ingénieur CI/CD	Créer/exécuter un pipeline de test	La tâche réussit
Nettoyer les ressources Docker	Mensuelle	Administrateur système	`docker system prune --filter "until=720h"`	Espace disque libéré
Examiner les runners enregistrés et les jetons	Trimestrielle	Équipe de sécurité	`gitlab-runner list` et examiner les accès	Seuls les runners nécessaires sont présents
Mettre à jour la version du runner	Trimestrielle ou selon la politique	Ingénieur CI/CD	Suivre la documentation de mise à niveau	Nouvelle version en cours d'exécution

Attribuez un responsable unique par élément pour éviter la dilution des responsabilités. Par exemple, l'ingénieur CI/CD est responsable de la vérification de version et du nettoyage mensuel, tandis que l'équipe de sécurité examine l'accès aux runners tous les trimestres. Révisez cette liste de contrôle chaque trimestre pour ajuster les fréquences en fonction de l'historique des incidents et des changements d'infrastructure. ## Pièges courants Plusieurs erreurs reviennent dans les opérations de production de GitLab Runner. Voici les plus courantes et comment les éviter ou s'en remettre. Modifier config.toml sans sauvegarde Les opérateurs modifient souvent la configuration directement et ne peuvent ensuite pas revenir en arrière en cas de problème. Créez toujours une sauvegarde horodatée avant de modifier, et conservez les sauvegardes pendant au moins une semaine. Ignorer la compatibilité des versions Utiliser une version de runner beaucoup plus ancienne ou plus récente que l'instance GitLab peut provoquer un comportement inattendu. Vérifiez la matrice de compatibilité avant de mettre à niveau l'un ou l'autre composant. Mettez à niveau le runner d'une version mineure à la fois si possible. Laisser la journalisation de débogage activée La journalisation de débogage génère de gros fichiers journaux et peut exposer des informations sensibles en texte clair. Activez-la uniquement pendant le dépannage actif et désactivez-la immédiatement après. Exécuter trop de tâches concurrentes sur un seul hôte Définir concurrent trop haut par rapport aux ressources disponibles entraîne des délais d'attente et des tueries OOM. Surveillez l'utilisation du CPU et de la mémoire. Augmentez la concurrence progressivement et testez avec des charges de travail représentatives. Ne pas nettoyer les images et volumes Docker L'espace disque se remplit, provoquant des échecs de build. Planifiez un docker system prune régulier avec des filtres appropriés et surveillez l'utilisation du disque avec df -h . Traiter le jeton d'enregistrement comme permanent Les jetons peuvent être révoqués ou pivotés. Si l'authentification échoue, réenregistrez le runner au lieu d'essayer de deviner le jeton. Conservez le jeton d'enregistrement dans un coffre sécurisé, pas en texte clair sur le disque. ## Conclusion Une liste de contrôle des opérations de production GitLab Runner n'est utile que si chaque recommandation est limitée à une version, observable et réversible lorsque la technologie le permet. Copier des commandes sans vérifier les prérequis et la sortie attendue n'est pas une procédure opérationnelle. Commencez par une vérification à faible risque : exécutez gitlab-runner --version et gitlab-runner verify sur votre runner, enregistrez l'état actuel et comparez les résultats avec les signaux attendus. Passez ensuite à la sauvegarde de votre configuration et à la planification de vérifications régulières. En suivant cette liste de contrôle, vous rendez les échecs visibles, protégez les valeurs sensibles, limitez les modifications à la ressource prévue et définissez la vérification de récupération avant qu'un incident ne force une décision. Des opérations fiables proviennent d'une observation disciplinée et de modifications incrémentales vérifiées.