Configuration d'un laboratoire local GitLab CI/CD avec exemples pratiques

Introduction

GitLab CI/CD automatise la livraison de logiciels via des pipelines définis dans un fichier .gitlab-ci.yml, mais tester des modifications directement sur une instance de production risque de perturber des projets réels et d'exposer des données sensibles. Un laboratoire local crée un environnement sûr et isolé où vous pouvez expérimenter avec les configurations de pipeline, déboguer les échecs et apprendre les concepts CI/CD sans conséquence. Ce guide détaille la mise en place d'une instance GitLab locale et d'un GitLab Runner sur une seule machine Linux, avec des exemples pratiques qui illustrent les concepts fondamentaux du CI/CD. À la fin, vous disposerez d'une configuration reproductible pour valider les pipelines avant leur arrivée sur une infrastructure partagée.

Inventaire des versions et de l'environnement

Avant de commencer, confirmez que votre environnement répond aux exigences. Les instructions supposent un hôte Linux ; Ubuntu 22.04 LTS est utilisé dans les exemples, mais des étapes similaires s'appliquent à d'autres distributions avec des modifications mineures.

Versions des logiciels

Topologie

Une seule machine héberge à la fois GitLab et le runner. GitLab fonctionne comme un service système sur le port HTTPS 443 (ou HTTP 80 si aucun TLS n'est configuré). Le runner s'enregistre auprès de GitLab à l'aide d'un jeton d'enregistrement et exécute les tâches localement en utilisant l'exécuteur shell par défaut. Pour les tâches conteneurisées, un exécuteur Docker peut être configuré si Docker est installé.

Prérequis

• 4 Go de RAM minimum (8 Go recommandés pour de meilleures performances)
• 10 Go d'espace disque libre
• Accès sudo ou root sur la machine
• Connectivité Internet pour télécharger les paquets

Étapes d'installation

Premièrement, mettez à jour les listes de paquets et installez les dépendances requises :

sudo apt update && sudo apt install -y curl openssh-server ca-certificates tzdata perl

Ajoutez le dépôt de paquets GitLab et installez GitLab CE. Remplacez http://gitlab.local par l'adresse IP ou le nom d'hôte de votre machine. L'installation peut prendre plusieurs minutes.

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo EXTERNAL_URL="http://gitlab.local" apt install gitlab-ce

Installez GitLab Runner en utilisant le script du dépôt officiel :

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner

Vérifiez que GitLab fonctionne en contrôlant l'état de ses services :

sudo gitlab-ctl status

La sortie attendue affiche une liste de services avec le statut run, par exemple :

run: gitlab-workhorse: (pid 1234) 10s; run: log: (pid 1233) 10s
run: logrotate: (pid 1235) 10s; run: log: (pid 1232) 10s
...

Après l'installation, accédez à l'interface web de GitLab en naviguant vers l'URL configurée. Lors de la première visite, vous serez invité à définir un mot de passe pour l'utilisateur root.

Chemin de configuration sûr

Commencez par une configuration minimale qui limite l'exposition et simplifie le débogage. Cette section couvre la création d'un projet de test, l'enregistrement d'un runner et la définition d'un pipeline de base.

Créer un projet

Créez un projet vierge dans GitLab via l'interface web ou l'API. Pour l'automatisation, utilisez l'API avec un jeton d'accès personnel (générez-le sous Paramètres utilisateur > Jetons d'accès avec la portée api).

curl --request POST --header "PRIVATE-TOKEN: <votre_jeton>" \
  --data "name=my-test-project&visibility=private" \
  "http://gitlab.local/api/v4/projects"

La sortie attendue comprend les détails du nouveau projet, tels que "id":1.

Enregistrer un runner

Enregistrez un runner avec l'exécuteur shell pour éviter des dépendances supplémentaires. D'abord, obtenez le jeton d'enregistrement du projet depuis l'interface web sous Paramètres > CI/CD > Runners (ou utilisez le jeton au niveau de l'instance pour les runners partagés). Ensuite, exécutez :

sudo gitlab-runner register

Lorsque vous y êtes invité, saisissez les informations suivantes :

• URL de l'instance GitLab (par exemple, http://gitlab.local)
• Jeton d'enregistrement provenant des paramètres CI/CD du projet
• Description (par exemple, local-shell-runner)
• Étiquettes (optionnel, par exemple, shell)
• Exécuteur : shell

Après l'enregistrement, le fichier de configuration du runner /etc/gitlab-runner/config.toml contiendra une entrée similaire à :

[[runners]]
  name = "local-shell-runner"
  url = "http://gitlab.local"
  token = "xxxxxxxxxxxx"
  executor = "shell"

Définir un pipeline de base

Créez un fichier .gitlab-ci.yml dans le dépôt du projet. Ce pipeline simple définit deux étapes (build et test) et affiche des informations sur l'environnement. La tâche build-job crée un artefact que la tâche test-job vérifie.

stages:
  - build
  - test

before_script:
  - echo "Démarrage de la tâche $CI_JOB_NAME"

build-job:
  stage: build
  script:
    - echo "Construction du projet..."
    - mkdir -p output
    - echo "Artefact de construction" > output/build.txt
  artifacts:
    paths:
      - output/

test-job:
  stage: test
  script:
    - echo "Exécution des tests..."
    - test -f output/build.txt && echo "Artefact trouvé"

Validez et poussez ce fichier pour déclencher le pipeline. Le before_script s'exécute avant chaque tâche, affichant le nom de la tâche. L'artefact de build-job est disponible dans test-job car les artefacts sont transmis entre les étapes par défaut.

Choix ciblés

• Utilisez l'exécuteur shell dans un premier temps pour éviter les complexités de configuration de Docker.
• Gardez le projet privé pour restreindre l'accès.
• Utilisez un runner distinct pour chaque projet afin d'isoler les ressources (ou utilisez des étiquettes pour orienter les tâches).

Vérification et diagnostics

Après avoir poussé la configuration du pipeline, vérifiez que les tâches s'exécutent correctement et inspectez les artefacts.

Statut du pipeline

Vérifiez le statut du pipeline via l'interface web (CI/CD > Pipelines) ou en utilisant la CLI GitLab (glab) si elle est installée :

glab ci status

Si vous utilisez l'API, récupérez le dernier pipeline pour l'ID de projet 1 :

curl --header "PRIVATE-TOKEN: <votre_jeton>" \
  "http://gitlab.local/api/v4/projects/1/pipelines/latest"

Recherchez "status":"success" dans la réponse JSON.

Journaux des tâches

Consultez les journaux des tâches pour confirmer que chaque étape s'est exécutée correctement. Dans l'interface web, accédez à CI/CD > Pipelines, puis cliquez sur le pipeline pour voir ses tâches. Cliquez sur une tâche pour voir son journal. Pour un runner shell, les journaux sont également stockés sur la machine du runner dans /var/log/gitlab-runner/, mais l'interface offre l'accès le plus simple.

Extrait de journal d'exemple pour build-job :

$ echo "Démarrage de la tâche build-job"
Démarrage de la tâche build-job
$ echo "Construction du projet..."
Construction du projet...
$ mkdir -p output
$ echo "Artefact de construction" > output/build.txt
Téléversement des artefacts pour une tâche réussie

Vérification du runner

Assurez-vous que le runner est actif et connecté :

sudo gitlab-runner verify

Sortie :

Vérification du runner... est vivant

Commandes de diagnostic courantes

• sudo gitlab-ctl tail - Afficher les journaux de GitLab
• sudo gitlab-runner --debug run - Exécuter le runner en mode débogage (premier plan)
• curl -I http://gitlab.local - Vérifier les en-têtes de réponse du serveur web

Modes de défaillance et récupération

Les échecs courants incluent des problèmes de connectivité du runner, des erreurs de permission et des pipelines mal configurés. Cette section décrit comment diagnostiquer et récupérer.

Le runner ne récupère pas les tâches

Symptômes : Le pipeline affiche en attente et le runner n'exécute pas les tâches.

Diagnostic : Vérifiez le statut du runner :

sudo gitlab-runner status

Vérifiez l'enregistrement du runner :

sudo gitlab-runner list

Récupération : Assurez-vous que le runner est enregistré pour le bon projet et que le jeton correspond. Sinon, réenregistrez-le avec le bon jeton :

sudo gitlab-runner register

Vérifiez également la connectivité réseau entre le runner et GitLab (ping, curl).

Erreurs de permission refusée

Symptômes : La tâche échoue avec Permission refusée lors de l'écriture de fichiers.

Diagnostic : L'exécuteur shell s'exécute en tant qu'utilisateur gitlab-runner, qui peut ne pas avoir les permissions d'écriture dans le répertoire de travail (par défaut : /home/gitlab-runner/builds).

Récupération : Ajustez les permissions ou utilisez un autre exécuteur. Pour une correction temporaire, ajoutez l'utilisateur gitlab-runner au groupe approprié (par exemple, www-data si vous construisez des fichiers web) et redémarrez le runner :

sudo usermod -aG www-data gitlab-runner
sudo systemctl restart gitlab-runner

Pour les problèmes persistants, envisagez d'utiliser l'exécuteur Docker pour isoler les permissions de fichiers.

Configuration YAML invalide

Symptômes : Le pipeline échoue immédiatement avec une erreur de syntaxe YAML.

Diagnostic : Utilisez un validateur YAML ou l'outil GitLab CI Lint disponible dans l'interface web (CI/CD > Pipelines > CI Lint). Collez le contenu du fichier .gitlab-ci.yml pour voir les erreurs de validation.

Récupération : Corrigez le YAML et poussez à nouveau. Les problèmes courants incluent une indentation incorrecte, des deux-points manquants ou l'utilisation de tabulations au lieu d'espaces.

Problèmes avec l'exécuteur Docker (si utilisé)

Symptômes : La tâche échoue avec Impossible de se connecter au démon Docker.

Diagnostic : Le service Docker n'est peut-être pas en cours d'exécution, ou le runner n'a pas les permissions pour accéder à la socket Docker.

Récupération : Démarrez Docker et ajoutez l'utilisateur du runner au groupe docker :

sudo systemctl start docker
sudo usermod -aG docker gitlab-runner
sudo systemctl restart gitlab-runner

Vérifiez que le runner peut exécuter des conteneurs Docker :

sudo -u gitlab-runner docker run hello-world

Retour en arrière

Pour annuler les modifications, éditez simplement le fichier .gitlab-ci.yml pour revenir à la dernière version connue comme fonctionnelle et poussez. Pour la configuration du runner, restaurez /etc/gitlab-runner/config.toml à partir d'une sauvegarde ou réenregistrez le runner.

Liste de contrôle des opérations

Utilisez cette liste de contrôle lors de la configuration ou de la modification de votre laboratoire local GitLab CI/CD.

Mettez régulièrement à jour GitLab et le runner vers les dernières versions de correctifs pour maintenir la compatibilité et la sécurité. Par exemple, exécutez sudo apt update && sudo apt upgrade gitlab-ce gitlab-runner mensuellement.

Conclusion

Un laboratoire local GitLab CI/CD est un atout précieux pour développer et tester des pipelines en toute sécurité. En suivant ce guide, vous avez installé GitLab et un runner, créé un projet de test, défini un pipeline de base et appris à vérifier et à résoudre les problèmes courants. Les prochaines étapes incluent l'expérimentation de fonctionnalités de pipeline plus complexes telles que les environnements, les déploiements multi-étapes et les tâches conteneurisées. Avec cette base, vous pouvez valider en toute confiance les configurations CI/CD avant de les promouvoir en production.