Lab 11 — Débugger un job bloqué

Quand un job est rouge, vous avez des logs. Quand un job reste en pending ou qu'un pipeline apparaît skipped, c'est plus déroutant : parfois il n'y a presque aucun indice visible. Ce lab vous donne une méthode de diagnostic fiable pour ces deux cas fréquents.

Objectif rapide

Vous allez appliquer une checklist opérationnelle pour distinguer un problème de runner d'un problème de règles CI.

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

• Diagnostiquer un job bloqué en pending
• Diagnostiquer un pipeline skipped
• Lire les indices utiles dans l'interface GitLab
• Corriger les causes les plus fréquentes

Quel lab commencer ?

Ce lab vient après Lab 10. Si vous avez déjà une base solide sur rules et workflow, vous pouvez commencer directement sur starter/lab-11.

Dans quel contexte ?

En environnement réel, ces incidents arrivent souvent juste avant une mise en production. Le stress monte parce que le pipeline n'avance pas, mais personne ne sait pourquoi. Sans méthode claire, l'équipe perd du temps à relancer des pipelines inutiles.

Ce lab vous sert pour :

• identifier un tag runner mal configuré
• détecter une règle workflow trop restrictive
• comprendre pourquoi un job ne démarre jamais alors que le code est correct

Prérequis

• Lab 10 — Rapports qualité terminé
• Avoir lu Debug pending et Debug skip

Point de départ

1. Basculez sur la branche du lab

   cd pipeline-craft
   git checkout starter/lab-11

2. Déclenchez un pipeline

   git push origin starter/lab-11

3. Ouvrez la vue pipeline

   Vous devriez observer au moins un comportement anormal (pending ou skipped).

Le problème

Deux symptômes différents demandent deux diagnostics différents.

Un job pending signifie généralement que GitLab n'a trouvé aucun runner compatible (tags, disponibilité, quota). Un pipeline skipped vient souvent des rules ou du workflow qui ne matchent pas la source courante.

L'exercice

Étape 1 — À vous de traiter un job pending

1. Ouvrez le job pending.

2. Vérifiez les messages d'assignation runner.

3. Contrôlez les tags du job dans .gitlab-ci.yml.

4. Vérifiez qu'un runner actif possède ces tags.

   Dans GitLab : Settings > CI/CD > Runners. Si aucun runner n'a le tag requis, le job restera pending indéfiniment.

👉 Vérifier votre solution (Étape 1)

1️⃣ Identifier la cause du pending

Ouvrez le job pending dans GitLab. Le message d'assignation indique la cause :

This job is stuck because no runners are online

ou

This job is stuck because the project doesn't have any runners online assigned to it

2️⃣ Vérifier les tags runner

Dans starter/lab-11, le job ruff-lint contient un tag inexistant :

ruff-lint:
  tags:
    - missing-runner-tag

Allez dans Settings > CI/CD > Runners et vérifiez les tags des runners disponibles.

3️⃣ Correction

Supprimez le bloc tags du job ruff-lint :

ruff-lint:
  stage: lint
  image: python:3.12-slim
  # plus de tags forcés

Étape 2 — À vous de traiter un pipeline skipped

1. Ouvrez le .gitlab-ci.yml.

2. Relisez le bloc workflow: rules.

3. Comparez les règles avec votre contexte réel (push, merge_request_event, tag).

   Indice : une règle qui ne couvre qu'un tag skippe volontairement les pushes standards.

👉 Vérifier votre solution (Étape 2)

1️⃣ Identifier la cause du skipped

Un pipeline skipped signifie qu'aucune règle workflow: ne correspond à la source courante.

starter/lab-11 contient un workflow: trop restrictif :

workflow:
  rules:
    - if: $CI_COMMIT_TAG

Si vous faites un git push sur une branche de feature, le pipeline est skipped — comportement voulu par vos règles.

Correction attendue dans solution/lab-11 :

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

Étape 3 — À vous de corriger puis valider

1. Ajustez tags/rules

2. Validez avec glab ci lint

   glab ci lint .gitlab-ci.yml

3. Poussez et observez un run normal

   git add .gitlab-ci.yml
   git commit -m "ci: fix pending/skipped root causes"
   git push origin starter/lab-11

👉 Vérifier votre solution (Étape 3)

1️⃣ Cycle de correction complet

# 1. Modifier .gitlab-ci.yml
# 2. Valider localement
glab ci lint .gitlab-ci.yml

# 3. Pousser une fois la validation verte
git add .gitlab-ci.yml
git commit -m "ci: fix pending/skipped root causes"
git push origin starter/lab-11

Observez le pipeline : les jobs doivent passer de pending ou skipped à running puis passed.

Le fichier complet

📄 Voir le fichier .gitlab-ci.yml complet

stages:
  - lint
  - test
  - build
  - deploy

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

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"

ruff-lint:
  stage: lint
  image: python:3.12-slim
  cache:
    key:
      files:
        - requirements-dev.txt
    paths:
      - .pip-cache/
    policy: pull
  before_script:
    - pip install ruff
  script:
    - ruff check app/ tests/

pytest:
  stage: test
  image: python:3.12-slim
  cache:
    key:
      files:
        - requirements-dev.txt
    paths:
      - .pip-cache/
  before_script:
    - pip install -r requirements-dev.txt
  script:
    - pytest -v --junitxml=report.xml --cov=app --cov-report=term-missing
  coverage: '/TOTAL\s+\d+\s+\d+\s+(\d+%)/'
  artifacts:
    when: always
    paths:
      - report.xml
    reports:
      junit: report.xml
    expire_in: 7 days

docker-build:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker build -t $CI_REGISTRY_IMAGE:latest .
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

deploy-staging:
  stage: deploy
  image: alpine:3.20
  script:
    - echo "Deploying $CI_COMMIT_SHORT_SHA to staging..."
    - ./scripts/deploy-demo.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-production:
  stage: deploy
  image: alpine:3.20
  script:
    - echo "Deploying $CI_COMMIT_SHORT_SHA to production..."
    - ./scripts/deploy-demo.sh production
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

Vérification

• Le job pending est pris par un runner
• Le pipeline n'est plus skipped de façon inattendue
• Les règles couvrent les sources de pipeline attendues
• La correction est reproductible sur un nouveau push

Pièges fréquents

Un job pending n'est pas un job cassé. C'est un job en attente de runner. Chercher une erreur applicative dans le code ne sert donc à rien à ce stade. Il faut d'abord résoudre l'assignation runner.

Pour skipped, le piège est de penser à un bug GitLab. Dans la majorité des cas, c'est le comportement voulu par vos règles, même si vous ne l'aviez pas anticipé.

À retenir

• pending et skipped sont des statuts de pilotage CI, pas des erreurs applicatives
• Les tags runner doivent correspondre exactement
• workflow: rules décide si le pipeline démarre
• Une checklist simple évite les diagnostics au hasard

Prochaines étapes

Lab 12 — Accélérer le pipeline Réduire fortement la durée de pipeline

Guide : debug pending Méthode détaillée côté runners

Guide : debug skipped Méthode détaillée côté rules

×

📖 Voir la documentation →