Automatisation CI/CD avec GitLab Runner : guide opérationnel pratique

Introduction

GitLab Runner est l'agent d'exécution qui traite les tâches CI/CD définies dans vos pipelines GitLab. Automatiser son installation, sa configuration et sa maintenance élimine les interventions manuelles, mais uniquement lorsque les changements sont versionnés, observables et réversibles. Ce guide présente une automatisation pratique de GitLab Runner destinée aux développeurs, consultants DevOps et équipes techniques de startups qui doivent passer d'un problème de configuration à un résultat vérifié sans élargir le rayon d'impact.

Chaque section associe une tâche opérationnelle spécifique à des observations en lecture seule, des commandes de modification minimale, le résultat attendu, les signaux d'échec et une procédure de récupération. Nous utilisons des valeurs fictives plutôt que de vrais identifiants, limitons chaque commande à la ressource visée et vérifions les résultats avant de poursuivre. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter l'impact et documenter le retour à un état connu et stable.

Inventaire des versions et de l'environnement

Avant toute automatisation ou modification, établissez l'état actuel de votre déploiement GitLab Runner. Commencez par identifier trois éléments : la version du runner installé, la topologie de déploiement et la plage de versions prise en charge par votre instance GitLab.

Observation en lecture seule

Exécutez la commande de version du runner sur l'hôte où il est installé :

gitlab-runner --version

Le résultat attendu ressemble à ceci :

Version:      15.11.0
Git revision: 12345678
Git branch:   15-11-stable
GO version:   go1.20.4
Built:        2023-04-21T12:00:00+0000
OS/Arch:      linux/amd64

Enregistrez ce résultat avec un horodatage. Vérifiez la compatibilité de la version du runner avec celle de votre serveur GitLab. GitLab maintient une matrice de compatibilité : un runner avec une ou deux versions mineures de retard fonctionne souvent, mais un runner d'une version majeure plus ancienne peut manquer des fonctionnalités de pipeline ou échouer à enregistrer des tâches.

Prérequis et rayon d'impact

L'automatisation des vérifications de version nécessite un accès SSH ou console à l'hôte du runner, des autorisations en lecture seule dans la zone d'administration GitLab, et l'emplacement du fichier de configuration du runner (par défaut /etc/gitlab-runner/config.toml sous Linux). Modifier la version du runner a un rayon d'impact moyen : cela affecte toutes les tâches que ce runner prend en charge. Assurez-vous de disposer d'une méthode de retour en arrière, comme une rétrogradation via le gestionnaire de paquets ou un instantané du fichier de configuration.

Modification minimale justifiée

Si une mise à niveau est nécessaire, mettez d'abord le runner en pause pour qu'il cesse de recevoir de nouvelles tâches, effectuez la mise à niveau, puis reprenez. Sous Debian/Ubuntu :

sudo gitlab-runner stop
sudo apt-get update && sudo apt-get install --only-upgrade gitlab-runner
sudo gitlab-runner start

Vérifiez la nouvelle version et assurez-vous que le runner se reconnecte :

gitlab-runner --version
gitlab-runner verify

Si verify indique un succès comme Verifying runner... is alive, la modification est terminée. En cas d'échec, revenez à la version précédente du paquet et restaurez le fichier de configuration.

Chemin de configuration sécurisé

La configuration du runner se trouve dans /etc/gitlab-runner/config.toml. Modifier directement ce fichier est risqué sans base de référence. Suivez un chemin sécurisé : sauvegarde, modification d'une seule section ciblée, validation de la syntaxe, rechargement et vérification avec une tâche de test.

Sauvegarde et observation

Tout d'abord, capturez la configuration actuelle et l'état du runner :

sudo cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.backup.$(date +%Y%m%d)
sudo gitlab-runner list

La commande list affiche les runners enregistrés et leurs types d'exécuteur. Notez quel runner sera affecté.

Exemple de modification : ajouter un nouveau runner avec exécuteur Docker

Une tâche d'automatisation courante consiste à ajouter un runner utilisant l'exécuteur Docker. Cette modification n'affecte que les nouvelles tâches assignées à ce runner, pas les runners existants. Les prérequis incluent Docker installé sur l'hôte et un jeton d'enregistrement GitLab (utilisez une valeur fictive ci-dessous).

Utilisez la commande d'enregistrement non interactive pour automatiser la configuration :

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "REMPLACEZ_PAR_JETON_ENREGISTREMENT" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "docker-runner-prod-1" \
  --tag-list "docker,linux" \
  --run-untagged="true" \
  --locked="false"

Après l'enregistrement, modifiez config.toml pour affiner les paramètres. Par exemple, augmentez la concurrence des tâches de 1 à 4 pour permettre des tâches parallèles :

Modifiez le paramètre de niveau supérieur concurrent :

concurrent = 4

Validez ensuite la syntaxe du fichier de configuration :

sudo gitlab-runner verify

Si la syntaxe est valide, la sortie listera chaque runner comme vivant. En cas d'erreur d'analyse, restaurez le fichier de sauvegarde et relancez verify.

Enfin, déclenchez un pipeline de test dans un projet temporaire pour confirmer que le nouveau runner prend en charge une tâche. Consultez les journaux de la tâche pour vérifier le nom du runner et la réussite de l'exécution.

Vérification et diagnostics

L'automatisation ne vaut que par sa vérification. Après toute modification, vous devez confirmer que le runner est sain, connecté à GitLab et capable d'exécuter des tâches.

Contrôle de santé du runner

Exécutez le contrôle de santé intégré :

sudo gitlab-runner health-check

Résultat attendu sur un runner sain :

Runtime platform                                    arch=amd64 os=linux pid=1234 revision=...
Checking GitLab API access                          ... ok
Checking the runner is registered                    ... ok
Checking the runner can execute jobs                 ... ok

Si une ligne signale une erreur, traitez-la avant d'exécuter de vrais pipelines. Par exemple, un échec de vérification de l'accès à l'API signifie souvent que le jeton d'enregistrement du runner a été révoqué ou que l'URL GitLab est incorrecte.

Commandes de diagnostic de pipeline

Utilisez l'API GitLab pour inspecter l'activité du runner côté serveur. La commande curl en lecture seule suivante liste les tâches d'un runner spécifique, en utilisant l'ID du runner depuis la zone d'administration :

curl --header "PRIVATE-TOKEN: REMPLACEZ_PAR_JETON_ACCES_PERSONNEL" \
  "https://gitlab.example.com/api/v4/runners/42/jobs?status=running"

La réponse JSON affiche chaque tâche en cours, son projet et l'ID du pipeline. Comparez-la avec les tâches actuellement sur votre hôte runner pour détecter les tâches orphelines ou l'accumulation en file d'attente.

Diagnostiquer une tâche bloquée

Une tâche bloquée à l'état pending signifie généralement qu'aucun runner ne peut la prendre en charge. Vérifiez la disponibilité des runners :

sudo gitlab-runner list

Recherchez le runner avec les bons tags. Consultez ensuite les journaux du runner pour détecter des erreurs :

sudo journalctl -u gitlab-runner -n 50 --no-pager

Recherchez des messages concernant des échecs d'enregistrement, des délais réseau ou un exécuteur non pris en charge. Corrigez le problème et relancez la tâche.

Modes d'échec et récupération

Même une automatisation soignée échoue. Préparez-vous aux modes d'échec courants avec des étapes de récupération claires.

Le runner cesse de prendre des tâches

Signal d'échec : les tâches restent en attente, le runner apparaît hors ligne dans l'administration GitLab. Vérifiez le processus du runner :

sudo systemctl status gitlab-runner

S'il est inactif, démarrez-le et activez-le au démarrage :

sudo systemctl start gitlab-runner
sudo systemctl enable gitlab-runner

Vérifiez ensuite avec gitlab-runner verify. Si le runner a été mis en pause dans GitLab (peut-être par un administrateur), reprenez-le via l'API ou l'interface d'administration. Documentez qui peut mettre en pause les runners et le contact de réponse aux incidents.

Configuration invalide après modification

Signal d'échec : gitlab-runner verify signale une erreur de syntaxe. Récupération : restaurez immédiatement la sauvegarde et rechargez :

sudo cp /etc/gitlab-runner/config.toml.backup.YYYYMMDD /etc/gitlab-runner/config.toml
sudo gitlab-runner restart

Corrigez la modification prévue dans un environnement de test avant de l'appliquer à nouveau.

L'exécuteur Docker ne parvient pas à extraire l'image

Signal d'échec : les journaux de tâche affichent Cannot connect to the Docker daemon ou pull access denied. Étapes de récupération :

Vérifiez l'état du démon Docker : sudo systemctl status docker
Vérifiez les autorisations Docker du runner : sudo usermod -aG docker gitlab-runner && sudo systemctl restart gitlab-runner
Vérifiez le nom de l'image et les identifiants du registre dans config.toml
Testez l'extraction manuellement en tant qu'utilisateur gitlab-runner.

Revenir en arrière après une mise à niveau du runner

Si un runner mis à niveau se comporte mal (par exemple, les tâches échouent avec de nouvelles erreurs), revenez à la version précédente. Sous Debian/Ubuntu :

sudo apt-get install gitlab-runner=NUMERO_VERSION

Restaurez ensuite la sauvegarde de configuration et vérifiez :

sudo cp /etc/gitlab-runner/config.toml.backup.YYYYMMDD /etc/gitlab-runner/config.toml
sudo gitlab-runner verify

Testez toujours les mises à niveau sur un runner de test d'abord.

Pièges courants et comment les éviter

Plusieurs erreurs reviennent fréquemment dans l'automatisation de GitLab Runner. Les connaître à l'avance évite des interruptions de service.

1. Modifier config.toml sans sauvegarde

Pourquoi cela arrive : correction rapide sous pression, ou supposition que gitlab-runner restart détectera les erreurs. Comment éviter : exécutez toujours cp avant de modifier. Automatisez la sauvegarde avec un script ou un outil de gestion de configuration. Récupérez en restaurant la sauvegarde et en utilisant verify avant de redémarrer.

2. Utiliser le même runner pour toutes les tâches sans tags

Pourquoi cela arrive : simplicité lors de la configuration initiale. À mesure que les pipelines se développent, les tâches avec des dépendances ou des besoins en ressources conflictuels restent bloquées sur le mauvais runner. Comment éviter : définissez des tags pour chaque runner et référencez-les dans .gitlab-ci.yml. Par exemple :

job_build:
  tags:
    - linux
    - docker

Récupérez en examinant les tags actuels avec gitlab-runner list, en ajoutant des tags et en mettant à jour les définitions de tâches.

3. Coder en dur des secrets dans la configuration du runner

Pourquoi cela arrive : transmettre des identifiants en texte brut dans config.toml ou dans --registration-token sur la ligne de commande. Comment éviter : utilisez les variables protégées de GitLab ou la gestion des secrets. Pour les identifiants de registre Docker, utilisez un assistant d'identification ou des variables d'environnement, jamais du texte brut dans la configuration.

4. Ignorer la compatibilité des versions du runner

Pourquoi cela arrive : supposer que les runners se mettent à jour automatiquement ou que n'importe quelle version fonctionne avec n'importe quel serveur GitLab. Comment éviter : figez les versions des runners et comparez régulièrement avec la matrice de compatibilité. Automatisez les vérifications de version avec un pipeline planifié.

5. Ne pas surveiller la santé du runner

Pourquoi cela arrive : après la configuration initiale, aucun contrôle continu. Les runners peuvent échouer silencieusement en raison d'un disque plein, de problèmes réseau ou d'expiration de jeton. Comment éviter : configurez une tâche de contrôle de santé simple dans GitLab CI qui s'exécute périodiquement et alerte en cas d'échec. Ou utilisez les métriques Prometheus exposées par le runner.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour chaque modification de GitLab Runner. Attribuez un responsable à la tâche globale et cochez chaque élément avec une preuve de vérification.

Étape	Action	Responsable	Résultat attendu	Fréquence
1	Enregistrer la version du runner et le hachage de la configuration	Ingénieur DevOps (Priya Shah)	Chaîne de version et sha256 de config.toml stockés	Avant chaque modification
2	Sauvegarder config.toml	Ingénieur DevOps	Fichier de sauvegarde avec horodatage	Avant chaque modification
3	Effectuer la modification la plus restreinte	Ingénieur DevOps	Modification déployée sur le runner de test d'abord	Par modification
4	Exécuter `gitlab-runner verify`	Ingénieur DevOps	Tous les runners vivants	Après modification
5	Déclencher un pipeline de test	Mainteneur CI/CD (Alex Chen)	La tâche réussit sur le runner prévu	Après modification
6	Surveiller la santé du runner pendant 1 heure	Ingénieur DevOps	Aucune erreur dans les journaux ou métriques	Post-déploiement
7	Documenter la modification et le plan de retour en arrière	Ingénieur DevOps	Entrée dans le runbook	Dans les 24 heures

Examinez cette liste de contrôle mensuellement avec l'équipe et mettez-la à jour si de nouveaux modes d'échec apparaissent.

Conclusion

L'automatisation CI/CD avec GitLab Runner est plus utile lorsque chaque étape est délibérée : observez l'état actuel, effectuez une petite modification, vérifiez le résultat et disposez d'un retour en arrière testé. Copier une commande sans vérifier les prérequis et le résultat attendu n'est pas une procédure opérationnelle.

Commencez par une vérification à faible risque de ce guide. Enregistrez la version de votre runner et sa configuration, exécutez une vérification en lecture seule, comparez le résultat au signal attendu, puis décidez si une automatisation supplémentaire est nécessaire. Un flux de travail fiable rend les échecs visibles, protège les valeurs sensibles et limite les modifications à la ressource prévue. En suivant les pratiques décrites ici, vous pouvez garder votre parc de GitLab Runner sain et vos pipelines fluides.