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

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	Dépendance manquante (import)
🔴 Bug 3	pytest	Configuration CI invalide (stage)

Glissez pour voir

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

L’exercice

Bug 1 — Le job ruff-lint échoue

1. Ouvrez les logs du job ruff-lint

   Allez dans Build > Pipelines, cliquez sur le pipeline en échec, puis sur le job ruff-lint. Cherchez les lignes en rouge dans la sortie.

2. Identifiez l’erreur

   Ruff signale deux erreurs dans app/main.py :

   app/main.py:3:8: F401 [*] `os` imported but unused
   app/main.py:3:1: I001 [*] Import block is un-sorted or un-formatted

   Ruff est un outil d’analyse statique de code Python (un “linter”). Il lit votre code et signale les problèmes sans l’exécuter. Ici, il a trouvé deux problèmes :

   • F401 : le code import os est présent en début de fichier, mais os n’est utilisé nulle part dans le reste du fichier. C’est un import mort. Ruff le signale parce qu’un import inutilisable peut masquer une vraie dépendance manquante.
   • I001 : l’import inutile désorganise l’ordre alphabetique des imports, ce que ruff exige aussi.

   Le format app/main.py:3:8 se lit : fichier app/main.py, ligne 3, colonne 8. C’est l’adresse exacte du problème dans le code.

3. Corrigez

   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 — Un import manquant dans le code de production

1. Cherchez dans les logs du job ruff-lint

   Ruff signale aussi une erreur dans app/routes/health.py :

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

   Le fichier health.py importe httpx — une bibliothèque de requêtes HTTP — mais ne l’utilise pas. De plus, httpx est uniquement dans requirements-dev.txt (dépendances de développement), pas dans requirements.txt (production). Si ce code arrivait en production, le docker build échouerait avec un ModuleNotFoundError.

2. Corrigez

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

   """Endpoint de health check."""
   
   from fastapi import APIRouter
   
   from app.models import HealthResponse

Bug 3 — Un stage invalide dans le CI

1. Regardez la vue d’ensemble du pipeline dans Build > Pipelines

   Ce bug est différent des deux premiers. Au lieu d’un message d’erreur dans les logs d’un job, vous allez voir le job pytest marqué comme impossible à créer directement au niveau du pipeline.

   Voici la différence :

   • Bugs 1 et 2 : le job démarre, tourne, et échoue — vous lisez l’erreur dans les logs du job
   • Bug 3 : GitLab refuse de créer le job à cause d’une configuration invalide — il n’y a pas de logs de job à lire, l’erreur apparaît directement dans la description du pipeline

   Cherchez le message d’erreur en haut de la page du pipeline ou cliquez sur le job pytest qui affiche un statut particulier (orange ou une icône de configuration erronée).

   Attention au message

   L’erreur de stage invalide peut apparaître directement au niveau du pipeline (et non dans les logs d’un job spécifique). GitLab refuse de créer le job si le stage référencé n’existe pas.

2. Identifiez l’erreur dans .gitlab-ci.yml

   Le job pytest déclare stage: tests (avec un s) — mais le stage défini dans stages: s’appelle test (sans s) :

   stages:
     - lint
     - test       # ← défini comme "test"
     - build
   
   pytest:
     stage: tests  # ← référence "tests" → n'existe pas !

   GitLab vérifie la configuration du .gitlab-ci.yml avant de lancer quoi que ce soit. Si un job référence un stage qui n’existe pas dans stages:, le pipeline s’arrête avant même d’essayer d’exécuter ce job. C’est une erreur de configuration, pas une erreur de code.

3. Corrigez

   Remplacez stage: tests par stage: test dans le job pytest :

   pytest:
     stage: test
     image: python:3.12-slim
     before_script:
       - pip install -r requirements-dev.txt
     script:
       - pytest -v

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

Ce qui a changé

app/main.py

 import os
  from fastapi import FastAPI

# app/routes/health.py
 import httpx
  from fastapi import APIRouter

# .gitlab-ci.yml
  pytest:
   stage: tests
   stage: test

Trois modifications minimales — mais chacune corrige un type d’erreur différent :

Fichier	Correction	Type
app/main.py	Suppression de import os inutilisé	Erreur de lint (F401)
app/routes/health.py	Suppression de import httpx inutilisé	Dépendance fantôme
.gitlab-ci.yml	tests → test	Erreur de configuration CI

Glissez pour voir

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 starter/lab-02..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 →