Debug : job bloqué sur pending

Votre job affiche “pending” depuis plusieurs minutes sans jamais démarrer ? Ce guide vous aide à identifier rapidement la cause et à débloquer votre pipeline.

Diagnostic rapide

1. “This job is stuck” → Tags ne correspondent pas
2. “Waiting for a runner” → Aucun runner disponible
3. Pending longtemps → Runners occupés ou quotas atteints

Les 5 causes de “pending”

Rang	Cause	Fréquence	Vérification
1	Tags incompatibles	35%	CI/CD > Runners
2	Runners offline	25%	Vérifier l’état des runners
3	Quotas épuisés / file saturée	15%	Settings > Usage Quotas
4	Runners occupés	10%	Attendre ou ajouter des runners
5	Run untagged jobs = false	10%	CI/CD > Runners > Options
6	Protected branch/runner	5%	Vérifier les protections

Glissez pour voir

Diagnostic pas à pas

1. Ouvrir le job en pending

   Cliquez sur le job. Le message d’erreur indique la cause.

2. Lire le message d’erreur

   • This job is stuck because... → Problème de tags
   • Waiting for a runner to pick up this job → Pas de runner dispo
   • Project runners are disabled → Runners désactivés

3. Vérifier les runners disponibles

   Settings > CI/CD > Runners montre :

   • Runners actifs (point vert)
   • Tags de chaque runner
   • Dernier contact

4. Comparer les tags

   Votre job demande des tags que le runner n’a pas ?

Cause #1 : Tags incompatibles (40%)

Symptôme : This job is stuck because you don't have any active runners that can run this job

Le job demande des tags que les runners n’ont pas.

Diagnostic :

# Votre job demande ces tags
deploy:
  tags:
    - docker
    - production

Mais votre runner a seulement docker, staging.

Solutions :

Solution rapide

Modifiez les tags du job pour correspondre aux runners disponibles :

deploy:
  tags:
    - docker    # Retirer 'production' si aucun runner ne l'a

Ou ajoutez les tags manquants au runner :

Option A (recommandée) : dans GitLab, allez dans CI/CD > Runners, cliquez sur le runner, modifiez les tags et sauvegardez.

Option B : si vous gérez le runner vous-même, les tags sont définis à l’enregistrement initial :

# Lors de l'enregistrement initial uniquement
gitlab-runner register \
  --tag-list "docker,production,staging"

Ne pas unregister pour changer les tags

Évitez gitlab-runner unregister puis register juste pour modifier les tags. Utilisez l’interface GitLab ou modifiez directement le config.toml si nécessaire.

Cause #2 : Runners offline (25%)

Symptôme : Runners avec point rouge ou gris dans Settings > CI/CD > Runners

Diagnostic :

Sur le serveur du runner :

# Vérifier le service (méthode la plus fiable)
systemctl status gitlab-runner

# Vérifier la connectivité avec GitLab
gitlab-runner verify

# Voir les logs récents
journalctl -u gitlab-runner -n 200 --no-pager

# Logs en temps réel
journalctl -u gitlab-runner -f

Solutions :

# Redémarrer le service
sudo systemctl restart gitlab-runner

# Vérifier que le runner se reconnecte
gitlab-runner verify

Token invalide

Si verify échoue avec une erreur de token, le runner doit être ré-enregistré depuis l’interface GitLab (nouveau token glrt-...).

Cause #3 : Quotas épuisés (20%)

Symptôme : Sur GitLab.com, jobs en attente même avec runners verts

GitLab.com limite les minutes de CI/CD selon votre plan.

Diagnostic :

Settings > Usage Quotas (ou groupe > Settings > Usage Quotas)

File d'attente saturée

Même sans quota épuisé, les shared runners GitLab.com peuvent être saturés (file d’attente). Le job reste pending en attendant qu’un runner se libère.

Solutions :

1. Attendre le début du mois (reset des quotas)
2. Acheter des minutes supplémentaires
3. Installer votre propre runner (pas de quota de minutes, mais limité par vos ressources et la configuration concurrent)

Cause #4 : Runners occupés (10%)

Symptôme : Pending pendant 1-5 minutes, puis démarre

Tous les runners exécutent d’autres jobs.

Diagnostic :

Regardez le paramètre concurrent du runner :

/etc/gitlab-runner/config.toml

concurrent = 4  # Nombre de jobs simultanés max

Solutions :

• Augmenter concurrent (si la machine le supporte)
• Ajouter des runners
• Optimiser les pipelines pour qu’ils soient plus courts

Cause #5 : Runner refuse les jobs non taggés (5%)

Symptôme : Le job n’a pas de tags, mais aucun runner ne le prend

Le runner est configuré avec “Run untagged jobs” = false. Il n’accepte que les jobs qui demandent explicitement ses tags.

Diagnostic :

Dans CI/CD > Runners, cliquez sur le runner et vérifiez l’option “Run untagged jobs”.

Solutions :

• Cocher “Run untagged jobs” sur le runner
• Ou ajouter des tags: à votre job pour correspondre aux tags du runner

Cause #6 : Protected branch/runner (5%)

Symptôme : Fonctionne sur certaines branches, pas sur d’autres

Le runner est marqué “protected” et ne s’exécute que sur les branches protégées.

Diagnostic :

Dans CI/CD > Runners, vérifiez si le runner a le badge “protected”.

Solutions :

• Décocher “Protected” sur le runner
• Protéger votre branche dans Settings > Repository > Protected branches

Checklist de debug

□ Le job a-t-il des tags ?
  → Oui : Vérifier qu'un runner a TOUS ces tags
  → Non : Vérifier qu'un runner a "Run untagged jobs" activé

□ Les runners sont-ils online ?
  → Settings > CI/CD > Runners (point vert)

□ Avez-vous des quotas ou une saturation ?
  → GitLab.com : Settings > Usage Quotas
  → Self-managed : pas de quota minutes, mais limité par `concurrent` et ressources

□ Le runner est-il protected ?
  → La branche est-elle protected aussi ?

□ Les shared runners sont-ils activés ?
  → CI/CD > Runners > "Enable shared runners"
  → Si désactivés, seuls vos runners projet/groupe peuvent exécuter

□ Le runner accepte-t-il les jobs sans tags ?
  → CI/CD > Runners > "Run untagged jobs"

Commandes utiles

# Sur le serveur du runner

# Vérifier le service
systemctl status gitlab-runner

# Liste des runners enregistrés
gitlab-runner list

# Vérifier la connexion à GitLab
gitlab-runner verify

# Logs en temps réel
journalctl -u gitlab-runner -f

Debug avancé : run-single

Pour reproduire un problème sur une machine de test :

gitlab-runner run-single \
  --url https://gitlab.com/ \
  --token TOKEN \
  --executor shell \
  --builds-dir /tmp/builds

À utiliser uniquement en environnement de test. Cette commande contourne le fonctionnement normal du service.

À retenir

1. “This job is stuck” = problème de tags ou “Run untagged jobs” désactivé
2. Tags : le job doit demander des tags que le runner possède
3. Run untagged jobs : si votre job n’a pas de tags, le runner doit accepter les jobs non taggés
4. Runner offline : systemctl status gitlab-runner et verify pour diagnostiquer
5. Quotas GitLab.com : vérifier Usage Quotas (ou file d’attente saturée)
6. Modifier les tags : via l’interface GitLab, pas en ré-enregistrant le runner

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 : pipeline skip Pourquoi mon pipeline entier est skipped ?

Debug : lire les logs Comprendre les erreurs dans les logs des jobs.

Rapports qualité JUnit, coverage — voir les résultats de tests.

×

📖 Voir la documentation →