Debug : pipeline skipped

Vous avez poussé du code mais le pipeline n’apparaît pas ou est marqué “skipped” ? Ce guide vous aide à comprendre pourquoi et à corriger le problème.

Diagnostic rapide

1. Pipeline skipped → workflow:rules ne matche pas ou [skip ci] dans le commit
2. Tous les jobs skipped → Aucun job n’a de rule qui matche
3. Pipeline non créé → Fichier .gitlab-ci.yml invalide, absent, ou workflow:rules exclut ce cas

Comprendre la différence

Situation	Symptôme	Cause
Pipeline skipped	Pipeline visible mais gris	workflow:rules ne matche pas ou [skip ci]
Jobs skipped	Pipeline vert mais jobs gris	rules: des jobs ne matchent pas
Pas de pipeline	Rien dans Pipelines	Fichier absent, invalide, ou workflow:rules exclut ce cas

Glissez pour voir

Cause #1 : workflow:rules ne matche pas

C’est la cause la plus fréquente. workflow:rules contrôle si le pipeline est créé.

Exemple de problème :

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    # ❌ Manque le cas des pushs !

# Ce pipeline ne se crée JAMAIS sur un push simple

Quand vous poussez sur une branche (sans MR ouverte), $CI_PIPELINE_SOURCE vaut push, pas merge_request_event. Aucune règle ne matche → pipeline skipped.

Solution :

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'    # ✅ Ajouter le cas des pushs

Règle d'or

Si aucune règle de workflow:rules ne matche, le pipeline est skipped. Assurez-vous de couvrir tous vos cas d’usage.

Cause #2 : Tous les jobs ont when: never

Si aucun job n’est ajouté au pipeline (rules qui ne matchent nulle part), le pipeline apparaît généralement skipped ou vide selon le type de pipeline.

Exemple :

build:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: never    # Exclus sur main
    - when: never    # Exclus partout ailleurs !

test:
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'
    # Sur main, aucune règle ne matche → job skipped

Sur main, les deux jobs sont skipped → pipeline skipped.

Diagnostic : vérifiez que au moins un job s’exécute dans chaque scénario.

Cas particulier : child pipelines

Dans les pipelines parent-enfant ou dynamiques, un pipeline sans job peut se manifester différemment (erreur au lieu de skipped). Vérifiez toujours avec le CI Lint.

Cause #3 : Fichier .gitlab-ci.yml invalide

Un fichier YAML invalide empêche la création du pipeline.

Diagnostic :

1. Build > Pipeline editor → Collez votre fichier → Validate
2. Utilisez l’option “Simulate pipeline creation” pour voir quelles rules bloquent
3. Ou Build > Pipelines → Message d’erreur en rouge

CI Lint : la méthode la plus fiable

Le CI Lint avec simulation permet de tester votre configuration avant de pusher. Il montre exactement quels jobs seraient créés selon vos variables.

Erreurs courantes :

Erreur	Cause	Solution
Invalid yaml syntax	Indentation incorrecte	Utiliser 2 espaces, pas de tabs
Unknown key	Faute de frappe	Vérifier l’orthographe (script pas scripts)
jobs:xxx:rules config should be an array	Mauvaise structure	rules: doit être une liste

Glissez pour voir

Cause #4 : Branche avec MR ouverte

GitLab évite les pipelines en double. Si une MR est ouverte pour votre branche, seul le pipeline MR s’exécute.

Exemple (pattern recommandé par GitLab) :

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never    # Skip si branche a une MR
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'

Avec cette config, pousser sur une branche avec MR ouverte ne crée pas de pipeline push (c’est voulu pour éviter les doublons).

Pattern officiel

Ce pattern est documenté par GitLab pour éviter les pipelines en double. Il garantit qu’un seul pipeline s’exécute par commit.

Cause #5 : Commit message [skip ci]

Un commit contenant [skip ci] ou [ci skip] dans son message provoque un pipeline skipped.

Piège courant : lors de la création d’une branche depuis un commit “skip ci”, le nouveau pipeline hérite de ce comportement.

Diagnostic :

Vérifiez le message du dernier commit :

git log -1 --format=%B

Solution : faites un nouveau commit sans [skip ci] ou utilisez Run pipeline depuis l’interface.

Variantes acceptées

GitLab reconnaît plusieurs formats : [skip ci], [ci skip], [no ci], et d’autres variantes. Le texte peut être n’importe où dans le message.

Diagnostic pas à pas

1. Vérifier que le fichier existe

   Le fichier doit s’appeler exactement .gitlab-ci.yml à la racine du repo.

2. Valider le YAML

   Build > Pipeline editor > Validate

3. Vérifier workflow:rules

   Quelles sont vos règles ? Matchent-elles votre cas ?

   workflow:
     rules:
       - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
       - if: '$CI_COMMIT_BRANCH'
       - if: '$CI_COMMIT_TAG'

4. Ajouter un job de debug

   debug:
     script:
       - echo "SOURCE=$CI_PIPELINE_SOURCE"
       - echo "BRANCH=$CI_COMMIT_BRANCH"
       - echo "TAG=$CI_COMMIT_TAG"
       - echo "MR=$CI_MERGE_REQUEST_ID"
     rules:
       - if: '$CI_PIPELINE_SOURCE'
         when: always

5. Utiliser le CI Lint avec simulation

   Build > Pipeline editor > Validate puis activez “Simulate pipeline creation” pour voir exactement quels jobs seraient créés.

Tableau de référence : sources de pipeline

Source	$CI_PIPELINE_SOURCE	Quand ?
Push	push	Commit poussé
Merge Request	merge_request_event	MR créée/mise à jour
Schedule	schedule	Pipeline planifié
Web	web	Bouton “Run pipeline”
API	api	Appel API
Trigger	trigger	Token de trigger
Parent	parent_pipeline	Pipeline parent-enfant
Multi-project	pipeline	Pipeline multi-projets

Glissez pour voir

Liste non exhaustive

D’autres valeurs existent selon les contextes (external_pull_request_event, chat, etc.). Consultez la documentation officielle GitLab pour la liste complète des variables prédéfinies.

Exemples de workflow:rules corrects

Pipeline sur push ET merge requests

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'

Pipeline sur push, mais pas si MR ouverte (éviter doublons)

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    - if: '$CI_COMMIT_BRANCH'

Pipeline sur tags uniquement

workflow:
  rules:
    - if: '$CI_COMMIT_TAG'

Pipeline partout sauf branches WIP

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH =~ /^wip-/'
      when: never
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'
    - if: '$CI_COMMIT_TAG'

Checklist de debug

□ Le fichier .gitlab-ci.yml existe-t-il à la racine ?
□ Le YAML est-il valide ? (Pipeline editor > Validate + Simulate)
□ Le commit contient-il [skip ci] ou [ci skip] ?
□ Y a-t-il une section workflow:rules ?
  → Oui : Couvre-t-elle votre cas (push, MR, schedule...) ?
  → Non : Le pipeline devrait se créer
□ Au moins un job a-t-il des rules qui matchent ?
□ La branche a-t-elle une MR ouverte ?
  → Vérifier si c'est voulu dans workflow:rules

À retenir

1. Pipeline skipped = workflow:rules ne matche pas ou [skip ci] dans le commit
2. Tous les jobs skipped = aucune rules: de job ne matche (pipeline vide)
3. Pas de pipeline = fichier invalide, absent, ou workflow:rules exclut ce cas
4. [skip ci] dans un commit peut affecter les branches créées depuis ce commit
5. Première règle qui matche gagne — ordre important
6. CI Lint + Simulate pour valider avant de pusher

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 : lire les logs Comprendre les erreurs dans les logs des jobs.

Rules (conditions) Maîtriser if, changes, exists et when.

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

×

📖 Voir la documentation →