Commandes de base de GitLab Runner avec exemples pratiques

Introduction

GitLab Runner est l'agent qui exécute les tâches dans les pipelines CI/CD de GitLab. Connaître les bonnes commandes peut transformer un échec déroutant en une solution rapide. Ce guide fournit une référence pratique, axée sur les commandes, pour les développeurs, les consultants DevOps et les équipes de startups techniques qui gèrent leurs propres runners.

Vous apprendrez à vérifier la version, à enregistrer et à vérifier les runners, à inspecter la configuration, à diagnostiquer les pannes courantes et à vous remettre d'une mauvaise configuration. Chaque commande comprend le résultat attendu, les signaux d'échec et des notes de sécurité. L'objectif est d'acquérir une confiance opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier les résultats et documenter les chemins de récupération.

Tous les exemples supposent un runner Linux installé via le paquet officiel. Les commandes sont compatibles avec GitLab Runner 15.x et 16.x, sauf indication contraire. Remplacez les espaces réservés comme <votre-jeton-d-enregistrement> par vos propres valeurs. Ne collez jamais de vrais jetons, clés privées ou identifiants de production dans des scripts ou de la documentation.

Inventaire de version et d'environnement

Avant de toucher à un runner, sachez exactement avec quoi vous travaillez. Exécutez ces commandes en lecture seule pour capturer la version, l'architecture et l'état du service.

Vérifier la version de GitLab Runner :

gitlab-runner --version

Résultat attendu (exemple) :

Version:      16.5.0
Git revision: 8a2c1b6e
Git branch:   16-5-stable
GO version:   go1.21.3
Built:        2023-10-20T14:32:11Z
OS/Arch:      linux/amd64

Si la commande renvoie command not found, le runner n'est pas installé ou n'est pas dans le $PATH actuel. Vérifiez les chemins d'installation courants tels que /usr/local/bin/gitlab-runner ou /usr/bin/gitlab-runner. Utilisez which gitlab-runner pour trouver l'exécutable.

Vérifier l'état du service runner :

sudo systemctl status gitlab-runner

Résultat attendu lorsqu'il est en cours d'exécution :

● gitlab-runner.service - GitLab Runner
   Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2023-12-04 09:15:42 UTC; 1h 12min ago
 Main PID: 1532 (gitlab-runner)
    Tasks: 11 (limit: 4915)
   CGroup: /system.slice/gitlab-runner.service
           └─1532 /usr/bin/gitlab-runner run --working-directory /home/gitlab-runner --config /etc/gitlab-runner/config.toml --service gitlab-runner --syslog

Si le service est inactive (dead) ou failed, ne redémarrez pas aveuglément. Inspectez d'abord les journaux pour comprendre pourquoi il s'est arrêté :

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

Recherchez les lignes contenant ERROR, FATAL ou des délais de connexion répétés. Les causes courantes incluent un config.toml invalide, une perte de connexion réseau à l'instance GitLab ou un disque plein.

Vérifier le sommaire de configuration du runner (lecture seule) :

sudo gitlab-runner verify --delete

Cette commande contacte le serveur GitLab et vérifie si chaque runner est toujours enregistré. Elle ne modifie pas la configuration locale sauf si --delete est utilisé, donc elle est sûre à exécuter. Résultat attendu :

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Running in system-mode.

Verifying runner... is alive                        runner=AbCdEfGh

Si vous voyez is not alive ou une erreur d'authentification, l'enregistrement du runner est cassé ou le jeton a été révoqué. Vous devrez le réenregistrer (voir Chemin de configuration sécurisé).

Vérifier l'espace disque :

Les runners peuvent remplir leur disque avec des artefacts de build et des images Docker. Utilisez :

df -h /var/lib/gitlab-runner

Résultat attendu :

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        50G   12G   36G  25% /

Si Use% est supérieur à 90 %, nettoyez les anciennes images Docker et les répertoires de build :

sudo docker system prune -af --volumes
sudo gitlab-runner cache-archive --path /var/lib/gitlab-runner/cache --delete-older-than 7d

La deuxième commande supprime les archives de cache de plus de 7 jours. Ajustez la durée selon les besoins. Vérifiez toujours l'espace disque après le nettoyage.

Vérifier le type de runner et l'exécuteur :

sudo gitlab-runner list

Résultat attendu :

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

Cela montre chaque runner configuré sur cet hôte, son type d'exécuteur et l'instance GitLab à laquelle il se connecte. Si la liste est vide, aucun runner n'est configuré ou le fichier config.toml est manquant.

Chemin de configuration sécurisé

Modifier la configuration du runner peut casser les pipelines. Suivez un processus contrôlé : sauvegardez, modifiez, vérifiez et soyez prêt à revenir en arrière.

Enregistrer un nouveau runner

La commande register est le changement de configuration le plus courant. Avant de l'exécuter, rassemblez ces prérequis :

• URL de l'instance GitLab (par ex. https://gitlab.example.com)
• Jeton d'enregistrement depuis les paramètres de votre projet > CI/CD > Runners, ou un jeton de groupe/d'instance
• Un nom descriptif pour le runner
• Un type d'exécuteur (docker, shell, kubernetes, etc.)
• Une liste de tags (optionnelle mais recommandée)

Exemple d'enregistrement pour un exécuteur Docker :

sudo gitlab-runner register \
  --non-interactive \
  --url https://gitlab.example.com \
  --registration-token <votre-jeton-d-enregistrement> \
  --executor docker \
  --docker-image alpine:latest \
  --description "ci-docker-runner-01" \
  --tag-list "docker,linux,small" \
  --run-untagged=false \
  --locked=false

Résultat attendu en cas de succès :

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Running in system-mode.

Registering runner... succeeded                     runner=AbCdEfGh
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

Vérification après l'enregistrement :

sudo gitlab-runner verify

Si vous voyez is alive pour le nouveau runner, il est correctement enregistré et peut se connecter au serveur GitLab. S'il indique is not alive, vérifiez que l'URL est joignable depuis l'hôte du runner et que le jeton n'a pas été mal saisi.

Modifier config.toml en toute sécurité

Tous les paramètres du runner se trouvent dans /etc/gitlab-runner/config.toml (installation système). Avant de modifier :

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

Après modification, exécutez toujours gitlab-runner verify à nouveau. S'il échoue, restaurez la sauvegarde :

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

Désenregistrer un runner

Si un runner n'est plus nécessaire, désenregistrez-le du serveur GitLab et supprimez sa configuration locale :

sudo gitlab-runner unregister --url https://gitlab.example.com --token <jeton-du-runner>

Le jeton du runner se trouve dans config.toml ou en exécutant sudo gitlab-runner list. Résultat attendu :

Unregistering runner... succeeded                  runner=AbCdEfGh

Après le désenregistrement, supprimez manuellement l'entrée du runner de config.toml si elle n'a pas été automatiquement supprimée, puis redémarrez le service.

Mettre à jour l'exécuteur du runner

Passer de l'exécuteur Docker à Shell, par exemple, nécessite de modifier config.toml. Changez ces lignes :

[[runners]]
  name = "my-shell-runner"
  url = "https://gitlab.example.com"
  token = "<votre-jeton>"
  executor = "shell"

Ensuite, redémarrez et vérifiez :

sudo gitlab-runner restart
sudo gitlab-runner verify

Si le runner affiche toujours l'ancien exécuteur dans gitlab-runner list, assurez-vous d'avoir modifié la bonne section du runner et que le service a chargé la nouvelle configuration.

Vérification et diagnostics

Utilisez ces commandes pour confirmer qu'un runner est sain, résoudre les échecs de tâches et inspecter les journaux de build.

Vérifier l'état du runner via l'API

Chaque runner peut être interrogé via l'API GitLab. Obtenez l'ID du runner à partir de gitlab-runner list ou de la page des paramètres CI. Ensuite :

curl --header "PRIVATE-TOKEN: <votre-jeton-d-acces-personnel>" \
  "https://gitlab.example.com/api/v4/runners/<runner_id>"

Réponse attendue (tronquée) :

{
  "id": 42,
  "description": "ci-docker-runner-01",
  "active": true,
  "online": true,
  "status": "online",
  "ip_address": "10.0.0.15",
  "runner_type": "project_type"
}

Si online est faux, le service runner est peut-être arrêté ou ne peut pas joindre GitLab. Vérifiez systemctl status gitlab-runner et la connectivité réseau.

Tester une tâche localement

Vous pouvez exécuter une tâche simple directement sans GitLab en utilisant gitlab-runner exec. Cela est utile pour déboguer les problèmes d'exécuteur.

Pour l'exécuteur Docker :

sudo gitlab-runner exec docker echo-test

Où echo-test est une tâche définie dans .gitlab-ci.yml :

echo-test:
  script:
    - echo "Hello from GitLab Runner"

Résultat attendu :

Running with gitlab-runner 16.5.0 (8a2c1b6e)
  on localhost 12345678
Preparing the "docker" executor
Using Docker executor with image alpine:latest ...
Pulling docker image alpine:latest ...
Using docker image sha256:... for alpine:latest ...
Preparing environment
Running on runner-12345678-project-1-concurrent-0 via hostname...
Getting source from Git repository
Fetching changes...
$ echo "Hello from GitLab Runner"
Hello from GitLab Runner
Job succeeded

Si la tâche échoue à Pulling docker image, le runner n'a peut-être pas accès à Docker Hub ou au registre configuré. Vérifiez l'état du démon Docker et la sortie réseau.

Consulter les journaux du runner pour une tâche

GitLab Runner écrit les journaux des tâches dans son propre fichier journal et dans l'interface GitLab. Pour les problèmes au niveau du système, suivez le journal du runner :

sudo tail -f /var/log/gitlab-runner/gitlab-runner.log

Pendant l'exécution d'une tâche, vous verrez des lignes comme :

Checking for jobs... received                       job=12345 repo_url=https://gitlab.example.com/group/project.git runner=AbCdEfGh
Job succeeded                                       duration_s=12.34 job=12345 project=42 runner=AbCdEfGh

Si une tâche se bloque ou échoue sans raison claire, augmentez temporairement la verbosité des journaux en définissant log_level = "debug" dans config.toml. Redémarrez le runner, reproduisez la tâche, puis remettez le niveau de journalisation à info.

Vérifier la concurrence et les limites du runner

Utilisez gitlab-runner status pour voir les tâches en cours et les limites :

sudo gitlab-runner status

Résultat attendu :

Runtime platform                                    arch=amd64 os=linux pid=12345 revision=8a2c1b6e version=16.5.0
Checking status of gitlab-runner...                 runner=runner-01
Service is running.                                  runner=runner-01
Concurrent jobs: 1 / 4                               runner=runner-01
Active jobs: 1                                       runner=runner-01
  12345: project 'my-project' job 'build' ... running runner=runner-01

Si Concurrent jobs est au maximum, les nouvelles tâches attendront. Augmentez concurrent dans config.toml si l'hôte a des ressources.

Modes de défaillance et récupération

Les runners échouent pour des raisons prévisibles. Voici les modes de défaillance les plus courants, comment les diagnostiquer et comment récupérer.

Échec : « Runner is not alive » ou « Authentication failed »

Cela signifie généralement que le jeton du runner est invalide ou que le runner a été désenregistré de GitLab. Diagnostiquez :

sudo gitlab-runner verify

Si la vérification échoue, vérifiez dans config.toml que le jeton est correct, et vérifiez dans l'interface GitLab sous Paramètres > CI/CD > Runners si le runner existe. Si le runner est manquant, réenregistrez-le en utilisant la commande register comme décrit précédemment.

Échec : Tâches bloquées en état « pending »

Cela signifie souvent qu'aucun runner ne prend en charge les tâches en raison d'une non-concordance des tags ou d'un runner hors ligne.

Vérifier les tags du runner : Dans .gitlab-ci.yml, une tâche peut spécifier tags: [docker]. Si les tags de votre runner sont docker,linux, ils devraient correspondre. Mais si la tâche spécifie tags: [windows], aucun runner ne la prendra.

Vérifier l'état en ligne du runner : Utilisez l'API ou gitlab-runner status. S'il est hors ligne, redémarrez le service :

sudo systemctl restart gitlab-runner
sudo systemctl status gitlab-runner

Si le service ne démarre pas, inspectez les journaux :

sudo journalctl -u gitlab-runner -n 100 --no-pager | grep -i error

Les erreurs de démarrage courantes incluent un config.toml malformé (par exemple, une section [[runners]] manquante) ou des options conflictuelles.

Échec : L'exécuteur Docker ne peut pas extraire l'image

Erreur dans le journal de la tâche : ERROR: Preparation failed: Error response from daemon: pull access denied for <image> ou no such host.

Correctif : Assurez-vous que l'hôte du runner peut joindre le registre d'images. Pour Docker Hub, testez :

docker pull alpine:latest

Si cela échoue, vérifiez le DNS et le pare-feu. Pour les registres privés, assurez-vous que le runner dispose des identifiants corrects. Ajoutez DOCKER_AUTH_CONFIG comme variable CI ou configurez les paramètres runners.docker dans config.toml pour inclure pull_policy = "if-not-present" afin d'utiliser les images locales lorsqu'elles sont disponibles.

Échec : Disque du runner plein

Si les tâches échouent avec No space left on device, vérifiez :

df -h /var/lib/gitlab-runner

Nettoyez les ressources Docker si vous utilisez l'exécuteur Docker :

sudo docker system prune -af --volumes

Nettoyez les anciens répertoires de build :

sudo find /var/lib/gitlab-runner/builds -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

Vérifiez l'espace récupéré et redémarrez le runner si nécessaire.

Échec : La tâche avec l'exécuteur Shell échoue avec permission refusée

Si l'utilisateur du runner ne peut pas écrire dans le répertoire de build, les tâches échouent. Vérifiez les permissions :

sudo ls -ld /var/lib/gitlab-runner
sudo ls -ld /var/lib/gitlab-runner/builds

Ils doivent appartenir à gitlab-runner:gitlab-runner. Corrigez avec :

sudo chown -R gitlab-runner:gitlab-runner /var/lib/gitlab-runner

Puis redémarrez le runner.

Liste de contrôle des opérations

Utilisez cette liste avant et après tout changement dans un environnement GitLab Runner.

Après tout changement, effectuez un test rapide en déclenchant un pipeline trivial sur un projet de test. Tenez un journal des changements avec horodatage pour faciliter le dépannage.

Conclusion

Maîtriser les commandes de GitLab Runner transforme une défaillance opaque en un diagnostic systématique. Les commandes de ce guide vous donnent une base solide pour les opérations quotidiennes : vérifications de version, enregistrement, vérification, diagnostics et récupération. Observez toujours avant de modifier, sauvegardez les configurations, utilisez des espaces réservés pour les secrets et vérifiez après chaque modification.

Comme prochaine étape, choisissez une vérification à faible risque de cet article et exécutez-la sur votre runner. Enregistrez l'état actuel, exécutez la vérification, comparez le résultat avec le résultat attendu, puis examinez les dépendances telles que GitLab CI/CD, Docker et Kubernetes. Créez un aide-mémoire local à partir de ces commandes et partagez-le avec votre équipe pour réduire le temps de réponse aux incidents.

Un flux de travail opérationnel fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Avec ces commandes GitLab Runner, vous pouvez opérer en toute confiance et maintenir vos pipelines CI/CD fluides.