Lab 02, Lire un échec et le corriger

Un collègue a poussé du code et le pipeline est tout rouge. Trois jobs échouent, chacun pour une raison différente. Personne ne comprend pourquoi, et le réflexe est de relancer le pipeline « au cas où ». Spoiler : relancer ne corrige rien. Dans ce lab, vous allez apprendre à lire les logs d'un pipeline GitLab pour identifier précisément ce qui casse, puis corriger chaque erreur.

En 30 secondes

Vous allez diagnostiquer 3 bugs en ne lisant que les logs des jobs. À la fin du lab, votre pipeline repasse au vert et vous savez lire une trace d'exécution GitLab CI/CD.

Série de labs

Cette page fait partie d'une série de labs progressifs sur Pipeline Craft. Pour comprendre le projet fil rouge, le workflow fork → starter → solution et la progression complète, commencez par Labs Pipeline Craft.

Ce que vous allez apprendre

• Lire les logs d'un job GitLab CI/CD pour identifier l'erreur exacte
• Distinguer les types d'erreurs : lint (code), runtime (import manquant), configuration CI (stage invalide)
• Corriger un pipeline cassé en modifiant le code et la configuration CI
• Comprendre les exit codes et leur impact sur le statut d'un job

Quel lab commencer ?

• Vous arrivez du Lab 01 → Vous êtes au bon endroit (Lab 02)
• Vous trouvez Lab 02 trop facile → Allez au Lab 03
• Vous voulez comprendre les diagnostics → Consultez Debug : lire les logs

Dans quel contexte ?

En entreprise, le pipeline rouge est le quotidien. Un collègue pousse du code sans tester localement, une dépendance disparaît, un copier-coller introduit une typo dans le .gitlab-ci.yml. Si vous ne savez pas lire les logs, vous perdez du temps à deviner, relancer, et deviner encore.

Situations réelles où ce lab vous aide :

• Un développeur junior a poussé du code qui casse le lint et ne comprend pas le message de ruff
• Une dépendance a été retirée de requirements.txt par erreur lors d'un merge
• Un job échoue avec un message unknown stage après un renommage
• L'équipe relance les pipelines « au cas où » au lieu de lire les logs

Prérequis

• Lab 01 complété, ou partir directement de la branche starter/lab-02
• Savoir naviguer dans l'interface GitLab (Build > Pipelines > cliquer sur un job)
• Avoir lu Debug : lire les logs d'un pipeline (conseillé)

Démarrage direct

Pas besoin d'avoir fait le Lab 01. La branche starter/lab-02 contient tout ce qu'il faut, y compris un .gitlab-ci.yml et les 3 bugs pré-injectés.

Point de départ

Si c'est votre premier lab, lisez d'abord la section Comment ça marche pour savoir comment forker et cloner le dépôt Pipeline Craft.

1. Passez sur la branche de départ de ce lab

   cd pipeline-craft
   git checkout starter/lab-02

   Cette branche contient le .gitlab-ci.yml du Lab 01, mais aussi 3 bugs que vous allez devoir trouver en lisant les logs du pipeline.

2. Poussez la branche pour déclencher le pipeline sur votre fork

   git push origin starter/lab-02

   Pourquoi pousser ?

   GitLab exécute un pipeline quand du code est poussé. Si la branche existait déjà sur votre fork (via le fork initial), le pipeline peut avoir déjà tourné. Dans ce cas, allez directement à l'étape suivante pour voir le résultat.

3. Observez le résultat dans Build > Pipelines sur votre fork GitLab

   Le pipeline démarre et… échoue. Vous voyez du rouge, c'est normal, c'est le but de ce lab.

Le problème

Le pipeline contient un .gitlab-ci.yml fonctionnel (celui du Lab 01), mais 3 erreurs ont été introduites. Chaque erreur affecte un aspect différent du pipeline :

Bug	Quel job est touché	Type d'erreur
🔴 Bug 1	ruff-lint	Erreur de code (lint)
🔴 Bug 2	ruff-lint	Erreur de code (lint)
🔴 Bug 3	pytest	Configuration CI invalide (stage)

Glissez pour voir

Votre mission : identifier et corriger les 3 erreurs en lisant les logs.

L'exercice

Étape 1, Observez le pipeline cassé

1. Passez sur la branche de départ de ce lab

   cd pipeline-craft
   git checkout starter/lab-02

   Cette branche contient le .gitlab-ci.yml du Lab 01, mais aussi 3 bugs que vous allez devoir diagnostiquer en lisant les logs du pipeline.

2. Poussez la branche pour déclencher le pipeline sur votre fork

   git push origin starter/lab-02

3. Observez le résultat dans Build > Pipelines sur votre fork GitLab

   Le pipeline démarre et affiche du rouge, c'est normal, c'est le but de ce lab. Prenez le temps d'explorer les logs avant de proposer des corrections.

Étape 2, Diagnostiquez les 3 bugs

Le pipeline contient des erreurs de trois types différents :

Bug	Quel job	Type d'erreur	À chercher dans les logs
🔴 Bug 1	ruff-lint	Erreur de code (lint)	F401, import inutilisé
🔴 Bug 2	ruff-lint	Erreur de code (lint)	F401, import inutilisé
🔴 Bug 3	pytest	Config CI invalide	unknown stage ou stage manquant

Glissez pour voir

À vous :

• Cliquez sur chaque job échoué pour lire ses logs
• Cherchez les erreurs correspondant à la table ci-dessus
• Notez le chemin du fichier et la ligne du problème (ex: app/main.py:3)
• Pas encore de corrections, juste l'identification des bugs

Format des logs GitLab

Chaque ligne de log peut avoir ce format :

app/main.py:3:8: F401 [*] `os` imported but unused

Cela veut dire : fichier app/main.py, ligne 3, colonne 8, code erreur F401.

Étape 3, À vous de proposer les corrections

Maintenant que vous avez identifié les 3 bugs, à vous de proposer les corrections. Vous devez modifier 3 fichiers :

1. app/main.py, Enlever une ligne problématique
2. app/routes/health.py, Enlever une ligne problématique
3. .gitlab-ci.yml, Corriger une typo

Indices :

• Pour les bugs 1 et 2 : ruff dit "imported but unused". La solution est logique : supprimez l'import inutilisé.
• Pour le bug 3 : le message d'erreur dans GitLab CI dit que le stage n'existe pas. Cherchez la typo dans le .gitlab-ci.yml (différence de 1 lettre).

Effectuez les corrections sur base de vos diagnostics. Quand vous pensez avoir trouvé les 3 solutions, vérifiez ci-dessous :

👉 Vérifier vos solutions

Bug 1, Import os inutilisé dans app/main.py

Ruff signale app/main.py:3:8: F401 [*] \os` imported but unused`.

Ouvrez app/main.py et supprimez la ligne import os :

"""Pipeline Craft — API FastAPI fil rouge pour les labs GitLab CI/CD."""

from fastapi import FastAPI

from app.config import settings
from app.routes import health, items, version

Bug 2, Import httpx inutilisé dans app/routes/health.py

Ruff signale app/routes/health.py:4:8: F401 [*] \httpx` imported but unused`.

Ouvrez app/routes/health.py et supprimez la ligne import httpx :

"""Endpoint de health check."""

from fastapi import APIRouter

from app.models import HealthResponse

Pourquoi c'est grave : httpx est uniquement dans requirements-dev.txt (dépendances de dev), pas dans requirements.txt (production). Si ce code restait, le docker build échouerait en production avec ModuleNotFoundError.

Bug 3, Stage invalide dans .gitlab-ci.yml

GitLab refuse de créer le job pytest. En regardant le .gitlab-ci.yml, vous trouvez :

stages:
  - lint
  - test       # ← défini comme "test"
  - build

pytest:
  stage: tests  # ← référence "tests" (avec un S) → n'existe pas !

Corrigez la typo :

pytest:
  stage: test   # ← maintenant "test" (sans S)
  image: python:3.12-slim
  before_script:
    - pip install -r requirements-dev.txt
  script:
    - pytest -v

Pourquoi c'est différent : GitLab valide le YAML avant de lancer les jobs. Si un stage n'existe pas, aucun job ne peut l'utiliser, c'est une erreur de configuration, pas une erreur d'exécution.

Étape 4, Vérifiez et poussez

1. Vérifiez localement que le lint passe

   ruff check app/ tests/

   Sortie attendue : All checks passed!

2. Committez et poussez

   git add app/main.py app/routes/health.py .gitlab-ci.yml
   git commit -m "fix: remove unused imports, fix stage name typo"
   git push origin starter/lab-02

3. Vérifiez le pipeline dans GitLab

   Un nouveau pipeline se déclenche automatiquement. Cette fois, les 3 jobs doivent passer au vert.

Vérification

• Les 3 erreurs identifiées uniquement via les logs (pas en parcourant le code au hasard)
• ruff check passe localement sans erreur
• Le pipeline GitLab affiche 3 jobs verts après le fix
• Vous savez expliquer la différence entre F401 (import inutilisé), un stage inconnu et un import de dépendance absente

Comment lire les logs efficacement

Quand un job échoue, les logs GitLab peuvent faire plusieurs centaines de lignes. Voici comment les lire sans se perdre :

1. Allez directement à la fin, l'erreur fatale est presque toujours dans les dernières lignes
2. Cherchez le code de sortie, exit code 1 signifie « erreur dans le script », exit code 127 signifie « commande introuvable »
3. Repérez les sections, GitLab structure les logs en sections pliables (before_script, script, after_script). L'erreur est dans la section rouge
4. Lisez le message complet, ne vous arrêtez pas à la première ligne d'erreur. Souvent, l'explication vient juste en dessous (ruff donne le numéro de ligne, pytest affiche la trace complète)

Exit code	Signification
0	Succès, le job est vert
1	Erreur dans le script (test échoué, lint en erreur, build cassé)
127	Commande introuvable (outil non installé)
137	Killed, le job a dépassé la limite mémoire (OOM)

Glissez pour voir

Debug avancé

Pour activer les logs détaillés de GitLab Runner, ajoutez la variable CI_DEBUG_TRACE: "true" dans votre job. Attention : cela affiche toutes les variables, y compris les secrets. Ne le faites jamais sur un dépôt public en production.

Pièges fréquents

Symptôme	Cause	Solution
« Relancer résoudra le problème »	Faux, si le code est cassé, relancer ne change rien	Lire les logs d'abord, corriger, puis pousser
Le pipeline échoue avant même de lancer un job	Erreur de syntaxe YAML ou stage inexistant	Vérifier le YAML dans Build > Pipeline editor
Ruff signale F401 mais ça ne casse pas pytest	Le lint et les tests sont indépendants, une erreur de lint n'empêche pas les tests de tourner	Corriger les deux : un code propre passe tous les jobs
ModuleNotFoundError dans le build Docker	Un import Python référence un paquet absent de requirements.txt	Soit ajouter le paquet dans requirements.txt, soit supprimer l'import inutile

Glissez pour voir

Pour aller plus loin

• Validez votre YAML localement avec la CLI glab : glab ci lint .gitlab-ci.yml vérifie la syntaxe et les stages sans pousser. Voir Valider un .gitlab-ci.yml.
• Explorez allow_failure: true : ajoutez cette clé à un job pour que le pipeline continue même si le job échoue (le job apparaît en orange). Utile pour les vérifications non bloquantes.
• Comparez avec solution/lab-02 : git diff origin/starter/lab-02..origin/solution/lab-02 montre exactement les 3 corrections attendues.

À retenir

• Lisez les logs, ne devinez pas, l'erreur exacte est toujours dans la sortie du job
• Un import inutilisé (F401) n'est pas juste du bruit : il peut masquer une dépendance fantôme qui cassera en production
• Un stage mal nommé empêche GitLab de créer le job, vérifiez que les noms dans stage: correspondent exactement à ceux de stages:
• La commande glab ci lint permet de détecter les erreurs de configuration CI avant de pousser
• Ne relancez jamais un pipeline sans avoir d'abord lu les logs du précédent échec

Prochaines étapes

Lab 03, Images et runners Optimisez les images Docker de vos jobs et comprenez où le code s'exécute

Debug : lire les logs Le guide complet sur la lecture des logs GitLab CI/CD

Valider un .gitlab-ci.yml Vérifier la syntaxe avant de pousser

← Lab 01 Revenir au premier lab

×

📖 Voir la documentation →