Debug : lire les logs GitLab CI/CD

Votre job a échoué avec un message cryptique dans les logs ? Ce guide vous apprend à lire les logs GitLab CI/CD efficacement et à identifier rapidement la cause des erreurs.

L'essentiel

1. Cherchez ERROR ou error: dans les logs
2. Regardez la dernière commande avant l’échec
3. Code de sortie ≠ 0 = échec (cherchez exit code)
4. Activez CI_DEBUG_TRACE pour le mode verbose

Structure des logs

Un job GitLab CI/CD s’exécute en plusieurs phases :

Chaque section est pliable dans l’interface. Cliquez sur une section pour voir son contenu.

Intitulés variables

Les intitulés exacts peuvent varier selon l’executor (Docker, Kubernetes, Shell), la version du runner et certaines fonctionnalités (cache distribué, etc.). L’ordre logique reste similaire.

Lire les logs : méthode rapide

1. Ouvrir le job en échec

   Build > Jobs → Cliquez sur le job rouge

2. Aller à la fin des logs

   Scrollez en bas ou cliquez sur le bouton “Scroll to bottom”

3. Trouver la dernière commande exécutée

   Juste avant Job failed se trouve la commande qui a échoué.

4. Lire le message d’erreur

   Remontez quelques lignes pour voir le message d’erreur complet.

Erreurs courantes et solutions

1. Commande non trouvée

$ npm run build
bash: npm: command not found

Cause : L’outil n’est pas installé dans l’image Docker.

Solutions :

• Utiliser une image qui contient l’outil : image: node:18
• Installer dans before_script : apt-get install -y nodejs npm

2. Fichier non trouvé

$ cat config.json
cat: config.json: No such file or directory

Cause : Le fichier n’existe pas ou mauvais chemin.

Solutions :

• Vérifier le chemin (absolu vs relatif)
• Ajouter ls -la avant pour lister les fichiers
• Vérifier que les artefacts sont bien téléchargés

3. Permission denied

$ ./deploy.sh
bash: ./deploy.sh: Permission denied

Cause : Le script n’est pas exécutable.

Solution :

before_script:
  - chmod +x deploy.sh

4. Tests échoués

FAIL src/utils.test.js
✕ should return correct value (5 ms)

Test Suites: 1 failed

Cause : Le code ne passe pas les tests.

Solution : Corriger le code ou les tests !

5. Code de sortie non nul

$ some_command
ERROR: Something went wrong
Job failed: exit code 1

Cause : La commande a retourné un code d’erreur.

Diagnostic : Lire le message ERROR au-dessus.

Mode debug : CI_DEBUG_TRACE

Pour voir toutes les commandes exécutées avec leurs valeurs :

variables:
  CI_DEBUG_TRACE: "true"

job:
  script:
    - echo $MY_SECRET    # Affichera la valeur !

Risque de fuite de secrets

CI_DEBUG_TRACE expose TOUTES les variables disponibles pour le job, y compris les secrets et tokens. Les logs deviennent visibles à tous ceux qui ont accès aux job logs.

• Activez-le uniquement via “Run pipeline” + variable temporaire
• Vérifiez que l’accès aux logs est restreint
• Supprimez les logs après analyse si le projet est public

Activer temporairement (sans modifier le fichier) :

1. Build > Pipelines > Run pipeline
2. Ajoutez la variable CI_DEBUG_TRACE = true
3. Lancez le pipeline

Ajouter vos propres logs de debug

build:
  script:
    # Afficher les variables d'environnement
    - echo "Branch: $CI_COMMIT_BRANCH"
    - echo "Source: $CI_PIPELINE_SOURCE"

    # Lister les fichiers
    - ls -la
    - pwd

    # Afficher le contenu d'un fichier
    - cat package.json

    # Votre commande
    - npm run build

Continuer malgré une erreur

Par défaut, le runner arrête le job à la première commande qui échoue (code de sortie ≠ 0). Pour continuer malgré une erreur :

job:
  script:
    - command_that_may_fail || true    # Continue même si erreur
    - another_command

Pièges avec | et &&

Pipes : avec set -o pipefail (actif par défaut sur certains runners), cmd1 | cmd2 échoue si n’importe quelle commande du pipe échoue, même si la dernière réussit. Classique avec grep qui retourne 1 si aucun match.

Chaînes && : cmd1 && cmd2 peut masquer des erreurs si mal utilisé. Préférez des commandes sur des lignes séparées pour un comportement prévisible.

Pour marquer un job comme “non bloquant” pour le pipeline :

job:
  allow_failure: true
  script:
    - risky_command

allow_failure ≠ || true

allow_failure: true ne fait pas “continuer” le job : le job échoue quand même, mais le pipeline continue (le job apparaît en orange/warning au lieu de rouge). Utilisez || true pour ignorer une erreur dans le job.

Télécharger les logs complets

Pour analyser offline ou partager :

1. Dans la page du job, bouton Download (à droite des logs)
2. Ou via API :

# Remplacez par l'URL de votre instance GitLab
# Le token doit avoir les droits read_api sur le projet
curl --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/jobs/$JOB_ID/trace" \
  > job.log

Logs des sections après échec

Même si le job échoue ou est annulé, after_script s’exécute. Utilisez-le pour collecter des infos :

job:
  script:
    - npm test
  after_script:
    # S'exécute même si npm test échoue ou si le job est annulé
    - echo "Job status: $CI_JOB_STATUS"    # success, failed, ou canceled
    - echo "Collecting debug info..."
    - cat npm-debug.log || true
    - ls -la node_modules/ || true

$CI_JOB_STATUS dans after_script

Pendant after_script, la variable $CI_JOB_STATUS contient le statut du job (success, failed, canceled). Utile pour adapter le nettoyage selon le résultat.

Chercher dans les logs

Dans l’interface GitLab :

1. Ctrl+F (ou Cmd+F) pour chercher dans la page
2. Cherchez : error, failed, not found, denied

En ligne de commande après téléchargement :

# Trouver les erreurs
grep -i "error\|failed\|denied" job.log

# Avec contexte (5 lignes avant/après)
grep -i -B5 -A5 "error" job.log

Logs runner vs logs job

Cette page couvre les logs de job (visibles dans l’interface GitLab). Si le job ne démarre pas ou si vous suspectez un problème d’executor/cache, consultez les logs du runner :

# Logs du service gitlab-runner
journalctl -u gitlab-runner -n 200

# Si executor Docker
docker logs gitlab-runner

# Si executor Kubernetes
kubectl logs -n gitlab-runner <pod-name>

À retenir

1. Scrollez en bas des logs pour voir l’erreur finale
2. exit code 1 = la commande a échoué, lire au-dessus
3. Sections pliables : cliquez pour ouvrir/fermer
4. CI_DEBUG_TRACE: true pour le mode verbose (⚠️ expose les secrets !)
5. after_script s’exécute même après échec ou annulation
6. allow_failure: true = le pipeline continue, mais le job échoue quand même
7. Pipes avec | : attention à pipefail qui peut faire échouer la ligne

Testez vos connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Debug : job pending Pourquoi mon job ne démarre pas ?

Debug : pipeline skip Pourquoi mon pipeline est skipped ?

Artefacts et cache Partager des fichiers entre jobs.

×

📖 Voir la documentation →