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

Avant de toucher au .gitlab-ci.yml, identifiez lequel des trois symptômes vous avez sous les yeux : ils se ressemblent dans l'interface mais ne se corrigent pas au même endroit. Le critère de tri est simple : allez dans Build > Pipelines et regardez si une ligne de pipeline existe. Si elle existe et qu'elle est grise, le problème est dans les règles. Si aucune ligne n'apparaît, GitLab n'a même pas réussi à lire votre configuration.

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"'
    # Incorrect : il 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'    # Correct : le cas des pushs est couvert

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 teste la configuration avant de pusher et détecte les problèmes de rules et de needs qu'une simple validation de syntaxe laisse passer. Une limite à connaître : la simulation se déroule comme un événement push sur la branche par défaut. Elle ne reproduit donc ni un pipeline de merge request, ni un tag, ni une branche de feature. Pour ces cas, le job de debug qui affiche les variables reste la méthode fiable.

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 : GitLab évalue le message du commit pointé par la référence poussée, pas celui que vous venez d'écrire. Créer une branche depuis un commit contenant [skip ci] sans rien ajouter dessus revient donc à pousser ce commit, et le pipeline est de nouveau skipped alors que vous n'avez rien demandé.

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 ne reconnaît que deux formes : [ci skip] et [skip ci], avec n'importe quelle casse et n'importe où dans le message de commit. Les variantes venues d'autres plateformes, comme [no ci] ou [skip actions] sur GitHub Actions, n'ont aucun effet sur GitLab et laisseront le pipeline partir. L'équivalent côté client Git est l'option de push git push -o ci.skip, qui ne saute pas les pipelines de merge request.

Diagnostic pas à pas

Suivez ces cinq vérifications dans l'ordre : elles vont du plus grossier au plus subtil, et chacune élimine une famille de causes. Les deux premières prennent dix secondes et écartent déjà la majorité des cas. L'étape 4, le job de debug, est la seule qui vous montre les valeurs réelles des variables dans votre contexte exact ; c'est elle qui tranche quand les règles ont l'air correctes sur le papier.

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 lancez la simulation pour voir quels jobs seraient créés lors d'un push sur la branche par défaut.

Tableau de référence : sources de pipeline

C'est la colonne du milieu qui vous intéresse : la valeur exacte à comparer dans un if:. Elle est sensible à la casse et s'écrit toujours en minuscules avec des underscores. Deux confusions reviennent souvent : push couvre à la fois les branches et les tags, et pipeline désigne les pipelines multi-projets, pas les pipelines enfants, qui prennent la valeur parent_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

C'est la configuration de départ recommandée quand vous ne savez pas encore quoi mettre. Elle accepte tout ce qui vient d'une merge request et tout ce qui vient d'une branche. Conséquence à assumer : pousser sur une branche qui a déjà une MR ouverte déclenche deux pipelines pour le même commit, et double la consommation de minutes de runner.

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

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

Cette variante corrige le doublon précédent. La règle en when: never ne bloque pas le pipeline de merge request, parce que $CI_COMMIT_BRANCH n'est pas définie dans un pipeline de MR : la condition ne peut pas correspondre. $CI_OPEN_MERGE_REQUESTS contient la liste des merge requests dont la branche courante est la source, et reste vide sinon. C'est le motif publié par GitLab pour ne garder qu'un seul pipeline par commit.

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

Configuration typique d'un dépôt de release : rien ne part au quotidien, tout se déclenche à la pose d'un tag. Sachez ce que vous acceptez avec cette règle : tous les pushs de branche et toutes les merge requests sont skipped, donc aucun test ne tourne avant le tag. Réservez-la aux dépôts dont le contenu est déjà validé ailleurs.

workflow:
  rules:
    - if: '$CI_COMMIT_TAG'

Pipeline partout sauf branches WIP

L'exclusion doit venir en premier, avant les règles qui acceptent : GitLab applique la première règle qui correspond et ignore les suivantes. Placée en dernier, la règle wip- ne serait jamais évaluée. Le =~ compare la variable à une expression régulière délimitée par des barres obliques, et l'accroche ^ la fait porter sur le début du nom de branche.

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

Parcourez cette liste dans l'ordre avant d'ouvrir un ticket ou de demander de l'aide : elle reprend les causes du guide, de la plus triviale à la plus subtile. Les trois premières lignes se vérifient sans quitter votre terminal. Si tout est coché et que le pipeline reste skipped, le problème est probablement une politique de sécurité au niveau du groupe, qui peut restreindre la création de pipelines ou le comportement de [skip ci].

□ 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

On passe à la pratique

Appliquez ces vérifications dans le Lab 11, Débugger un job bloqué.

Testez vos connaissances

Ces questions portent sur les cinq causes décrites ci-dessus et sur la lecture de workflow:rules. Si vous hésitez entre pipeline skipped et pipeline non créé, relisez le premier tableau avant de commencer.

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

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

Déclencheurs Push, MR, tags, schedules, comprendre CI_PIPELINE_SOURCE.

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

×

📖 Voir la documentation →