Dépannage rapide des builds échoués avec l'interface CLI Jenkins

L'interface web Jenkins est utile pour explorer. L'interface CLI Jenkins est plus adaptée lorsque vous connaissez déjà le nom de la tâche, avez besoin du log immédiatement ou souhaitez répéter les mêmes vérifications sans cliquer sur plusieurs pages.

Un build échoué nécessite généralement trois informations : ce qui a été exécuté, où il a échoué et ce qui a changé depuis le dernier bon build. L'interface CLI peut récupérer ces trois éléments rapidement si vous la configurez une fois.

Configurer une commande CLI réutilisable

Téléchargez le fichier JAR CLI depuis votre propre contrôleur Jenkins :

curl -O "$JENKINS_URL/jnlpJars/jenkins-cli.jar"

Utilisez un jeton API, pas votre mot de passe de compte :

export JENKINS_URL="https://jenkins.example.com"
export JENKINS_USER="votre-utilisateur"
export JENKINS_API_TOKEN="votre-jeton-api"

alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Testez l'authentification avant de résoudre un véritable échec :

jcli who-am-i
jcli help

Si cela échoue, corrigez d'abord l'accès CLI. Les causes courantes sont une URL incorrecte, un jeton copié avec un espace supplémentaire, des permissions manquantes ou un paramètre de sécurité Jenkins qui désactive le transport CLI que vous essayez d'utiliser.

Pour les scripts partagés, évitez les alias shell. Enveloppez la commande dans un petit script ou utilisez des variables d'environnement dans votre stockage de secrets CI afin que les jetons ne se retrouvent pas dans l'historique du shell.

Trouver le build échoué

Si vous connaissez le nom de la tâche et le numéro du build, passez directement au log de la console. Si vous savez seulement que quelque chose a échoué récemment, commencez par Groovy via l'interface CLI :

jcli groovy = <<'EOF'
Jenkins.instance.getAllItems(hudson.model.Job.class).each { job ->
  def b = job.getLastBuild()
  if (b != null && b.result == hudson.model.Result.FAILURE) {
    println "${job.fullName} #${b.number} ${b.getTime()}"
  }
}
EOF

Pour les dossiers et les pipelines multibranches, utilisez le nom complet de la tâche exactement comme Jenkins le connaît. Une tâche de branche pourrait ressembler à :

team-service/main
team-service/PR-42
dossier-a/dossier-b/deploy-prod

Si un nom contient des espaces, mettez-le entre guillemets dans votre shell :

jcli console "Dossier Avec Espaces/Mon Pipeline" 128

Récupérer d'abord le log de la console

Le log de la console reste la source de vérité la plus rapide pour la plupart des échecs :

jcli console MonPipelineJob 123

Pour les logs longs, sauvegardez une copie et recherchez avec contexte :

jcli console MonPipelineJob 123 > build-123.log
grep -niE "error|failed|exception|traceback|permission denied|timeout" build-123.log | head -40
grep -niC 3 "permission denied" build-123.log

Ne vous fiez pas uniquement à la première ligne contenant "error". Les outils de build affichent souvent des avertissements, des noms de tests ou du texte d'échec attendu. Recherchez le premier échec significatif après le début de l'étape, puis lisez les lignes précédentes. La cause se trouve souvent au-dessus de la trace de la pile.

Pour un build en cours d'exécution, suivez le log :

jcli console MonPipelineJob 123 -f

Certaines versions de Jenkins et modes CLI acceptent --follow ; d'autres utilisent -f. Vérifiez jcli help console sur votre contrôleur.

Identifier l'étape qui a échoué

Les logs de pipeline incluent des marqueurs d'étape. Recherchez-les près de l'échec :

grep -n "\[Pipeline\] stage" build-123.log

Inspectez ensuite la section après le dernier marqueur d'étape avant l'erreur. Si le log est bruyant, ouvrez-le avec less :

less build-123.log

Dans less, recherchez /ERROR, /Exception ou /[Pipeline] stage.

Un bon Jenkinsfile facilite cela en affichant des noms d'étape clairs avant les opérations risquées :

echo 'Installation des dépendances npm'
sh 'npm ci'
echo 'Exécution des tests unitaires'
sh 'npm test'

Si chaque étape est simplement sh './ci.sh', l'interface CLI peut toujours récupérer le log, mais le log peut ne pas vous en dire assez. Dans ce cas, améliorez le pipeline après l'incident.

Vérifier les paramètres et les causes

Un build peut échouer parce qu'il a été exécuté avec la mauvaise branche, le mauvais environnement ou un paramètre obsolète. Récupérez les métadonnées du build avec Groovy :

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MonPipelineJob')
def build = job?.getBuildByNumber(123)
if (build == null) {
  println 'Build non trouvé'
  return
}
println "Tâche : ${job.fullName}"
println "Build : #${build.number}"
println "Résultat : ${build.result}"
println "Durée : ${build.durationString}"
println 'Causes :'
build.getCauses().each { println "- ${it.shortDescription}" }
println 'Paramètres :'
build.getAction(hudson.model.ParametersAction)?.parameters?.each {
  println "- ${it.name}=${it.value}"
}
EOF

C'est particulièrement utile pour les tâches de déploiement. Un déploiement de production échoué avec BRANCH=feature/test est un problème très différent d'un déploiement échoué de l'étiquette de version attendue.

Soyez prudent lors de l'affichage des variables d'environnement. Elles peuvent contenir des secrets. Si vous avez besoin de détails sur l'environnement, imprimez des clés spécifiques sécurisées plutôt que de tout vider :

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MonPipelineJob')
def build = job?.getBuildByNumber(123)
def env = build?.getEnvironment(TaskListener.NULL)
['JOB_NAME', 'BUILD_NUMBER', 'BRANCH_NAME', 'GIT_COMMIT', 'NODE_NAME'].each { key ->
  println "${key}=${env?.get(key)}"
}
EOF

Si votre script manque de permissions ou si un plugin modifie les métadonnées disponibles, revenez au log de la console et à la configuration de la tâche.

Comparer avec le dernier build réussi

Un seul log échoué est utile. Un log échoué à côté du dernier log réussi est encore mieux.

Trouvez le numéro du dernier build réussi :

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MonPipelineJob')
def b = job?.getLastSuccessfulBuild()
println b == null ? 'Aucun build réussi trouvé' : b.number
EOF

Récupérez ensuite les deux logs :

jcli console MonPipelineJob 122 > build-122-reussi.log
jcli console MonPipelineJob 123 > build-123-echoue.log

Comparez les commandes, les versions des dépendances, les étiquettes d'agent, les branches et les SHA de checkout. De nombreux échecs proviennent d'une image de base modifiée, d'une dépendance déplacée, d'un agent différent ou d'un identifiant expiré entre les builds.

Pour les pipelines basés sur Git, ces valeurs sont souvent suffisantes pour commencer :

grep -nE "Checking out|GIT_COMMIT|BRANCH_NAME|git rev-parse|Docker|image:" build-123-echoue.log

Relancer un build avec précaution

Une fois que vous comprenez l'échec ou que vous avez appliqué un correctif, déclenchez un nouveau build :

jcli build MonPipelineJob

Pour les tâches paramétrées :

jcli build MonPipelineJob -p BRANCH=main -p ENVIRONMENT=staging

Pour attendre et diffuser la sortie, vérifiez les options prises en charge par votre contrôleur :

jcli help build

Les options courantes incluent l'attente de la fin et l'affichage de la sortie de la console, mais les noms peuvent varier selon la version de Jenkins et les plugins.

Ne relancez pas les tâches de déploiement de production juste pour voir ce qui se passe. Confirmez d'abord les paramètres, les identifiants et l'environnement cible. Si la tâche n'est pas idempotente, une relance peut aggraver l'incident.

Utiliser la sortie CLI dans les notes d'incident

L'interface CLI est utile pour laisser une trace. Sauvegardez le log exact et les métadonnées que vous avez utilisées :

mkdir -p incident-jenkins-123
jcli console MonPipelineJob 123 > incident-jenkins-123/console.log
jcli get-job MonPipelineJob > incident-jenkins-123/job-config.xml

Considérez job-config.xml comme sensible s'il contient des références d'identifiants, des URL ou des noms internes. Ne le collez pas dans des tickets publics.

Une note d'incident compacte pourrait inclure :

Tâche : MonPipelineJob #123
Étape échouée : Tests unitaires
Première commande échouée : npm test
Commit : abc1234
Agent : linux-build-07
Cause probable : l'installation des dépendances a utilisé Node 22 au lieu de Node 20 attendu
Action : version de l'outil fixée et relance #124 réussie

C'est bien plus utile que "Jenkins a échoué."

Un flux de dépannage pratique

Utilisez cet ordre lorsqu'un build échoue et que vous avez besoin d'informations rapidement :

jcli who-am-i
jcli console MonPipelineJob 123 > build-123.log
grep -niE "error|failed|exception|permission denied|timeout" build-123.log | head -40
grep -n "\[Pipeline\] stage" build-123.log

Inspectez ensuite les paramètres et les causes avec Groovy, comparez avec le dernier build réussi, et relancez seulement après avoir déterminé si l'échec était dû au code, à l'infrastructure, aux identifiants ou aux paramètres d'entrée.

L'interface CLI Jenkins ne diagnostiquera pas magiquement chaque build échoué. Ce qu'elle fait bien, c'est supprimer les frictions. Elle récupère le log, les métadonnées et la commande de relance dans votre terminal rapidement, où vous pouvez rechercher, différencier, sauvegarder et répéter les mêmes vérifications la prochaine fois qu'un pipeline échoue.