Configuration locale de GitLab Runner avec exemples pratiques

Un laboratoire local GitLab Runner vous offre un environnement sûr et réinitialisable pour tester des jobs, diagnostiquer des comportements et apprendre par la pratique sans toucher à l'infrastructure partagée. Dans ce guide, vous allez :

• Installer GitLab Runner pour un usage local.
• Choisir une configuration sécurisée qui limite le rayon d'impact.
• Exécuter deux exemples pratiques avec les exécuteurs shell et Docker.
• Vérifier les résultats et capturer les diagnostics.
• Reconnaître les modes de défaillance courants et récupérer rapidement.
• Utiliser une liste de contrôle reproductible pour les opérations quotidiennes.

L'idée centrale est simple : gardez votre premier pilote étroit, mesurable et facile à inspecter localement avant tout déploiement plus large. Cette approche accélère l'apprentissage et réduit les reprises.

Inventaire des versions et de l'environnement

Avant de toucher à quoi que ce soit, notez exactement ce que vous allez exécuter. Cela transforme « ça marche sur ma machine » en étapes reproductibles que vos collègues peuvent suivre.

Conseils :

• Utilisez un compte non-root dédié pour toutes les actions du labo.
• Gardez les fichiers du labo sous une seule arborescence de répertoires pour pouvoir les sauvegarder ou les supprimer en une seule étape.
• Si vous expérimentez avec Docker, assurez-vous que votre utilisateur est dans le groupe docker et que les images sont pré-téléchargées quand le réseau est lent ou restreint.

Chemin de configuration sécurisé

Un labo local sûr est intentionnellement petit et contrôlé. Les choix suivants vous gardent rapide et en sécurité :

• Portée : commencez avec des exécutions locales « exec » (sans enregistrement auprès d'un serveur GitLab). Vous pourrez ajouter l'enregistrement plus tard si vous voulez tester des pipelines complets, mais l'exec local suffit pour la plupart des expériences.
• Identité : créez un utilisateur non-root dédié, par exemple « runnerlab ».
• Répertoires : utilisez des répertoires par labo comme ~/lab/work, ~/lab/cache et ~/lab/logs. N'utilisez pas de répertoires système.
• Choix d'exécuteur :
• Exécuteur shell : le plus simple, utilise vos outils hôte. Excellent pour le prototypage de commandes et les vérifications rapides.
• Exécuteur Docker : optionnel, utile quand vous avez besoin d'une chaîne d'outils propre ou d'une isolation au niveau OS.
• Privilèges : évitez les conteneurs privilégiés et évitez de monter des chemins hôtes sensibles.
• Garde-fous de ressources : gardez les jobs petits. Si vous utilisez Docker, évitez les grosses images et pré-téléchargez ce dont vous avez besoin. Sur l'hôte, évitez les jobs qui épuisent la mémoire.

Un comparatif rapide pour guider votre choix :

Étapes d'implémentation

Les commandes ci-dessous ciblent Linux (type Ubuntu/Debian). Adaptez les chemins pour d'autres plateformes.

1. Créer un utilisateur de labo dédié

# Créer un utilisateur non-root pour le travail de labo
sudo useradd -m -s /bin/bash runnerlab

# Créer les répertoires du labo (en tant qu'utilisateur du labo)
sudo -iu runnerlab bash -lc '
 mkdir -p ~/lab/{work,cache,logs}
 printf "Répertoires du labo créés sous : %s\n" "$HOME/lab"
'

2. Installer GitLab Runner (binaire autonome)

# Télécharger et installer le binaire GitLab Runner
sudo curl -L -o /usr/local/bin/gitlab-runner \
 https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
sudo chmod +x /usr/local/bin/gitlab-runner

# Vérifier l'installation
gitlab-runner --version
# Résultat attendu : une ligne de version comme "Version: 16.x" plus les infos de build.

3. (Optionnel) Installer Docker pour l'exécuteur Docker

# Installer le moteur Docker (exemple Ubuntu)
sudo apt-get update
sudo apt-get install -y docker.io

# Autoriser l'utilisateur du labo à accéder au socket Docker
sudo groupadd -f docker
sudo usermod -aG docker runnerlab

# Rafraîchir l'appartenance au groupe dans le shell courant (nouvelle connexion fonctionne aussi)
sudo -iu runnerlab bash -lc 'id && docker info >/dev/null && echo Docker OK'
# Résultat attendu : l'utilisateur du labo est dans le groupe docker et "docker info" réussit sans sudo.

Exemples pratiques

Les exemples utilisent gitlab-runner exec qui exécute un job depuis un .gitlab-ci.yml local sans enregistrer un runner auprès d'une instance GitLab.

Notes importantes :

• Chaque exemple s'exécute dans votre répertoire de travail courant, gardez donc les fichiers sous ~/lab/work.
• Vous pouvez surcharger les emplacements de build et de cache avec des drapeaux pour tout garder dans votre arborescence de labo.

Exemple 1 : Exécuteur shell, afficher les infos système

1. Préparer un répertoire de travail et un fichier de pipeline minimal

sudo -iu runnerlab bash -lc '
 mkdir -p ~/lab/work/example1 && cd ~/lab/work/example1
 cat > .gitlab-ci.yml <<"YAML"
lab_echo:
 stage: test
 script:
 - echo "Hello from shell executor"
 - uname -a
 - printf "PWD=%s\n" "$PWD"
 - echo "Done"
YAML
 printf "Créé : %s/.gitlab-ci.yml\n" "$PWD"
'

2. Exécuter le job localement avec l'exécuteur shell

sudo -iu runnerlab bash -lc '
 cd ~/lab/work/example1
 gitlab-runner exec shell lab_echo \
 --builds-dir "$HOME/lab/work" \
 --cache-dir "$HOME/lab/cache" \
 2>&1 | tee "$HOME/lab/logs/example1_shell.log"
'

Résultat attendu :

• La sortie commence par « Running with gitlab-runner... » et « Using Shell (bash) executor ».
• Vos lignes echo, uname et PWD apparaissent.
• La ligne finale affiche « Job succeeded ».

Pour ré-exécuter proprement, relancez simplement la même commande ; rien ne reste derrière sauf le log que vous avez choisi de sauvegarder.

Exemple 2 : Exécuteur Docker, exécuter un test Python

Cet exemple lance un petit test Python dans une image de conteneur pour démontrer l'isolation.

1. Préparer les fichiers

sudo -iu runnerlab bash -lc '
 mkdir -p ~/lab/work/example2/tests && cd ~/lab/work/example2
 # Un petit fichier de test
 cat > tests/test_math.py <<"PY"
import math

def test_add():
 assert 2 + 2 == 4

def test_sqrt():
 assert math.isclose(math.sqrt(9), 3.0)
PY

 # Pipeline minimal qui installe pytest et lance les tests
 cat > .gitlab-ci.yml <<"YAML"
lab_pytest:
 image: python:3.11-slim
 stage: test
 before_script:
 - python --version
 - pip install --no-cache-dir pytest==7.4.4
 script:
 - pytest -q
YAML
 printf "Créé example2 avec tests et .gitlab-ci.yml\n"
'

2. Pré-télécharger l'image (optionnel mais accélère le premier run)

sudo -iu runnerlab docker pull python:3.11-slim

3. Exécuter le job localement avec l'exécuteur Docker

sudo -iu runnerlab bash -lc '
 cd ~/lab/work/example2
 gitlab-runner exec docker lab_pytest \
 --builds-dir "$HOME/lab/work" \
 --cache-dir "$HOME/lab/cache" \
 --docker-pull-policy if-not-present \
 2>&1 | tee "$HOME/lab/logs/example2_docker.log"
'

Résultat attendu :

• La sortie affiche « Using Docker executor » et l'image python:3.11-slim.
• La version Python s'affiche, pytest s'installe, et 2 tests passent.
• La ligne finale affiche « Job succeeded ».

Vérification et diagnostics

Ces vérifications confirment que votre labo est sain et accélèrent le dépannage.

Astuces supplémentaires :

• Augmenter la verbosité : ajoutez --debug à toute commande gitlab-runner.

sudo -iu runnerlab bash -lc '
 cd ~/lab/work/example1
 gitlab-runner --debug exec shell lab_echo | sed -n "1,60p"
'

• Forcer un espace de travail propre en supprimant les répertoires de build sous votre chemin lab work si un run antérieur a laissé des artefacts.
• Pour l'exécuteur Docker, pré-téléchargez les images et vérifiez les digests d'image quand vous avez besoin de reproductibilité.
• Épinglez les versions des outils de langage ou des frameworks de test dans vos scripts de job pour que les re-runs se comportent de la même façon.

Modes de défaillance et récupération

Problèmes courants et correctifs rapides :

1. Permission refusée sur le socket Docker

• Symptôme : « Got permission denied while trying to connect to the Docker daemon socket »
• Correctif :

sudo usermod -aG docker runnerlab
# Nouvelle connexion requise pour prendre en compte le groupe ; puis vérifier
sudo -iu runnerlab docker info

2. Commande introuvable dans un job shell

• Symptôme : Un outil fonctionne dans votre shell de connexion mais pas dans le job.
• Cause : PATH différent ou l'outil n'est pas installé pour l'utilisateur du labo.
• Correctif : Installez l'outil pour l'hôte ou préfixez les commandes avec un chemin déterministe, ex. /usr/bin/env python3. Dans .gitlab-ci.yml vous pouvez aussi définir PATH ou installer les prérequis dans before_script.

3. Erreurs YAML ou de guillemets

• Symptôme : gitlab-runner échoue à parser le job ou le shell traite les arguments incorrectement.
• Correctif : Utilisez une indentation YAML correcte et mettez entre guillemets les chaînes avec espaces. Exemple :

script:
 - bash -lc 'echo "Valeur : $MYVAR"'

4. Téléchargements d'images Docker lents ou en échec

• Symptôme : Timeouts ou erreurs 429 lors du pull.
• Correctif : Pré-téléchargez l'image ; utilisez --docker-pull-policy if-not-present ; choisissez une image de base plus petite.

5. Fichiers résiduels qui cassent les re-runs

• Symptôme : Un run précédent a laissé des produits de build qui changent le comportement.
• Correctif :

sudo -iu runnerlab bash -lc '
 cd ~/lab/work/example2
 git clean -fdx || true
'

6. Interpréteur mal assorti

• Symptôme : « python: command not found » ou différences de shell.
• Correctif : Utilisez des interpréteurs explicites (python3). Pour les shells non-bash par défaut, faites passer les lignes de script par bash -lc.

Étapes de rollback et récupération

• Revenir à une version GitLab Runner connue bonne :

# Garder une copie d'un binaire fonctionnel
sudo cp /usr/local/bin/gitlab-runner /usr/local/bin/gitlab-runner.good
# Si vous mettez à jour et régressez, faites un rollback rapide
sudo mv /usr/local/bin/gitlab-runner.good /usr/local/bin/gitlab-runner
sudo chmod +x /usr/local/bin/gitlab-runner
gitlab-runner --version

• Supprimer les artefacts du labo (reset doux) :

sudo -iu runnerlab bash -lc 'rm -rf ~/lab/work/* ~/lab/cache/* ~/lab/logs/*'

• Désinstaller complètement (reset dur) :

# Arrêter les services utilisateur que vous auriez créés (le cas échéant)
# Puis supprimer l'utilisateur et le binaire
sudo userdel -r runnerlab || true
sudo rm -f /usr/local/bin/gitlab-runner

Vérification après récupération :

• Confirmez que la version du runner est celle attendue.
• Confirmez que les répertoires du labo sont recréés avant de relancer les exemples.
• Relancez l'Exemple 1 pour valider la ligne de base.

Liste de contrôle des opérations

Utilisez cette liste pour garder les expériences prévisibles et révisables.

Préparation

• Confirmez que l'OS, l'utilisateur et les versions correspondent à votre tableau d'inventaire.
• Assurez-vous que l'utilisateur du labo existe et peut lancer gitlab-runner --version.
• Pour les tests Docker, confirmez que docker info fonctionne pour l'utilisateur du labo et que les images requises sont tirées.

Vérifications pré-run

• Assurez-vous que .gitlab-ci.yml existe dans le répertoire de travail et que les noms de jobs correspondent.
• Optionnellement, nettoyez le répertoire de travail ou lancez dans un nouveau dossier.
• Décidez des drapeaux builds-dir et cache-dir pour que les artefacts restent dans l'arborescence du labo.

Exécution

• Lancez gitlab-runner exec shell JOB ou gitlab-runner exec docker JOB.
• Capturez stdout/stderr vers un log sous ~/lab/logs.

Après run

• Vérifiez la ligne finale « Job succeeded ».
• Relisez le log pour les avertissements et durées.
• Sauvegardez ou supprimez les artefacts sous votre chemin lab work selon les besoins.

Hygiène périodique

• Élaguez les vieilles images si vous utilisez Docker et que le stockage est serré.
• Nettoyez les répertoires de cache pour éviter les dépendances obsolètes.
• Mettez à jour GitLab Runner délibérément ; notez le changement de version dans votre inventaire.

Conclusion

Vous disposez maintenant d'un petit labo GitLab Runner sûr en qui vous pouvez avoir confiance pour tester et apprendre :

• Un utilisateur non-root dédié et un répertoire de labo gardent les expériences isolées.
• L'exécuteur shell vous donne le chemin le plus rapide vers la validation locale.
• L'exécuteur Docker ajoute une isolation de chaîne d'outils propre quand c'est nécessaire.
• Des étapes de vérification claires, des sorties attendues et des logs rendent les résultats faciles à revoir.
• Les modes de défaillance connus ont des correctifs courts, déterministes et un rollback.
• Une liste de contrôle légère garde les opérations reproductibles.

Prochaines étapes :

• Étendez vos jobs locaux avec des étapes de build et de test réalistes, en gardant chaque changement petit et mesurable.
• Épinglez les versions pour les outils et images pour que les re-runs soient cohérents.
• Quand vous êtes à l'aise, enregistrez un runner contre un projet non-production pour tester des flux de pipeline complets, en suivant toujours les mêmes principes de sécurité.

Un pilote étroit et mesurable qui s'exécute localement de bout en bout construit la confiance rapidement et réduit les reprises à mesure que vous étendez votre usage de GitLab Runner.