Schnelle Fehlerbehebung fehlgeschlagener Builds mit der Jenkins CLI

Die Jenkins-Weboberfläche ist nützlich, wenn Sie erkunden. Die Jenkins CLI ist besser, wenn Sie den Jobnamen bereits kennen, das Log sofort benötigen oder dieselben Überprüfungen wiederholen möchten, ohne durch Seiten klicken zu müssen.

Ein fehlgeschlagener Build erfordert in der Regel drei Informationen: Was wurde ausgeführt, wo ist er fehlgeschlagen und was hat sich seit dem letzten erfolgreichen Lauf geändert. Die CLI kann alle drei schnell abrufen, wenn Sie sie einmal eingerichtet haben.

Einrichten eines wiederholbaren CLI-Befehls

Laden Sie das CLI-JAR von Ihrem eigenen Jenkins-Controller herunter:

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

Verwenden Sie einen API-Token, nicht Ihr Kontopasswort:

export JENKINS_URL="https://jenkins.example.com"
export JENKINS_USER="your-user"
export JENKINS_API_TOKEN="your-api-token"

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

Testen Sie die Authentifizierung, bevor Sie einen echten Fehler beheben:

jcli who-am-i
jcli help

Wenn dies fehlschlägt, beheben Sie zuerst den CLI-Zugriff. Häufige Ursachen sind eine falsche URL, ein Token mit einem zusätzlichen Leerzeichen, fehlende Berechtigungen oder eine Jenkins-Sicherheitseinstellung, die den von Ihnen verwendeten CLI-Transport deaktiviert.

Vermeiden Sie für gemeinsame Skripte Shell-Aliase. Verpacken Sie den Befehl in ein kleines Skript oder verwenden Sie Umgebungsvariablen in Ihrem CI-Geheimnisspeicher, damit Token nicht in der Shell-Historie landen.

Finden des fehlgeschlagenen Builds

Wenn Sie den Jobnamen und die Build-Nummer kennen, gehen Sie direkt zum Konsolenlog. Wenn Sie nur wissen, dass kürzlich etwas fehlgeschlagen ist, beginnen Sie mit Groovy über die 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

Verwenden Sie für Ordner und Multibranch-Pipelines den vollständigen Jobnamen genau so, wie Jenkins ihn kennt. Ein Branch-Job könnte so aussehen:

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

Wenn ein Name Leerzeichen enthält, setzen Sie ihn in Ihrer Shell in Anführungszeichen:

jcli console "Ordner mit Leerzeichen/Meine Pipeline" 128

Zuerst das Konsolenlog abrufen

Das Konsolenlog ist immer noch die schnellste Quelle der Wahrheit für die meisten Fehler:

jcli console MyPipelineJob 123

Für lange Logs speichern Sie eine Kopie und suchen Sie mit Kontext:

jcli console MyPipelineJob 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

Verlassen Sie sich nicht nur auf die erste Zeile, die "error" enthält. Build-Tools drucken oft Warnungen, Testnamen oder erwartete Fehlertexte. Suchen Sie nach dem ersten aussagekräftigen Fehler nach dem Start der Stufe und lesen Sie dann die Zeilen davor. Die Ursache liegt oft oberhalb des Stack-Trace.

Folgen Sie für einen laufenden Build dem Log:

jcli console MyPipelineJob 123 -f

Einige Jenkins-Versionen und CLI-Modi akzeptieren --follow; andere verwenden -f. Überprüfen Sie jcli help console auf Ihrem Controller.

Identifizieren der fehlgeschlagenen Stufe

Pipeline-Logs enthalten Stufenmarkierungen. Suchen Sie in der Nähe des Fehlers danach:

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

Überprüfen Sie dann den Abschnitt nach der letzten Stufenmarkierung vor dem Fehler. Wenn das Log verrauscht ist, öffnen Sie es mit less:

less build-123.log

Suchen Sie in less nach /ERROR, /Exception oder /[Pipeline] stage.

Ein gutes Jenkinsfile erleichtert dies, indem es vor riskanten Operationen klare Schrittnamen ausgibt:

echo 'Installiere npm-Abhängigkeiten'
sh 'npm ci'
echo 'Führe Unit-Tests aus'
sh 'npm test'

Wenn jeder Schritt nur sh './ci.sh' ist, kann die CLI zwar das Log abrufen, aber das Log sagt Ihnen möglicherweise nicht genug. Verbessern Sie in diesem Fall die Pipeline nach dem Vorfall.

Überprüfen von Parametern und Ursachen

Ein Build kann fehlschlagen, weil er mit dem falschen Branch, der falschen Umgebung oder einem veralteten Parameter ausgeführt wurde. Rufen Sie die Build-Metadaten mit Groovy ab:

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MyPipelineJob')
def build = job?.getBuildByNumber(123)
if (build == null) {
  println 'Build nicht gefunden'
  return
}
println "Job: ${job.fullName}"
println "Build: #${build.number}"
println "Ergebnis: ${build.result}"
println "Dauer: ${build.durationString}"
println 'Ursachen:'
build.getCauses().each { println "- ${it.shortDescription}" }
println 'Parameter:'
build.getAction(hudson.model.ParametersAction)?.parameters?.each {
  println "- ${it.name}=${it.value}"
}
EOF

Dies ist besonders hilfreich für Bereitstellungsjobs. Ein fehlgeschlagener Produktions-Deployment mit BRANCH=feature/test ist ein ganz anderes Problem als ein fehlgeschlagener Deployment des erwarteten Release-Tags.

Seien Sie vorsichtig beim Drucken von Umgebungsvariablen. Sie können Geheimnisse enthalten. Wenn Sie Umgebungsdetails benötigen, drucken Sie bestimmte sichere Schlüssel anstatt alles auszugeben:

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MyPipelineJob')
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

Wenn Ihrem Skript die Berechtigung fehlt oder ein Plugin die verfügbaren Metadaten ändert, greifen Sie auf das Konsolenlog und die Jobkonfiguration zurück.

Vergleich mit dem letzten erfolgreichen Build

Ein einzelnes fehlgeschlagenes Log ist nützlich. Ein fehlgeschlagenes Log neben dem letzten erfolgreichen Log ist besser.

Finden Sie die letzte erfolgreiche Build-Nummer:

jcli groovy = <<'EOF'
def job = Jenkins.instance.getItemByFullName('MyPipelineJob')
def b = job?.getLastSuccessfulBuild()
println b == null ? 'Kein erfolgreicher Build gefunden' : b.number
EOF

Rufen Sie dann beide Logs ab:

jcli console MyPipelineJob 122 > build-122-success.log
jcli console MyPipelineJob 123 > build-123-failed.log

Vergleichen Sie die Befehle, Abhängigkeitsversionen, Agent-Labels, Branches und Checkout-SHAs. Viele Fehler kommen von einem geänderten Basis-Image, einer verschobenen Abhängigkeit, einem anderen Agenten oder einer Anmeldeinformation, die zwischen Builds abgelaufen ist.

Für Git-basierte Pipelines reichen diese Werte oft aus, um zu beginnen:

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

Einen Build sorgfältig neu starten

Sobald Sie den Fehler verstanden oder eine Korrektur angewendet haben, lösen Sie einen neuen Build aus:

jcli build MyPipelineJob

Für parametrisierte Jobs:

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

Um zu warten und die Ausgabe zu streamen, überprüfen Sie die unterstützten Optionen Ihres Controllers:

jcli help build

Häufige Optionen umfassen das Warten auf den Abschluss und das Drucken der Konsolenausgabe, aber die Namen können je nach Jenkins-Version und Plugins variieren.

Starten Sie Produktions-Deployment-Jobs nicht neu, nur um zu sehen, was passiert. Bestätigen Sie zuerst Parameter, Anmeldeinformationen und Zielumgebung. Wenn der Job nicht idempotent ist, kann ein Neustart den Vorfall verschlimmern.

Verwenden der CLI-Ausgabe in Vorfallnotizen

Die CLI eignet sich gut, um eine Spur zu hinterlassen. Speichern Sie das genaue Log und die von Ihnen verwendeten Metadaten:

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

Behandeln Sie job-config.xml als sensibel, wenn es Verweise auf Anmeldeinformationen, URLs oder interne Namen enthält. Fügen Sie es nicht in öffentliche Tickets ein.

Eine kompakte Vorfallnotiz könnte Folgendes enthalten:

Job: MyPipelineJob #123
Fehlgeschlagene Stufe: Unit-Tests
Erster fehlgeschlagener Befehl: npm test
Commit: abc1234
Agent: linux-build-07
Wahrscheinliche Ursache: Abhängigkeitsinstallation verwendete Node 22 anstelle von erwartetem Node 20
Maßnahme: Tool-Version festgelegt und #124 erfolgreich neu gestartet

Das ist weitaus nützlicher als "Jenkins fehlgeschlagen."

Ein praktischer Fehlerbehebungsablauf

Verwenden Sie diese Reihenfolge, wenn ein Build fehlschlägt und Sie schnell ein Signal benötigen:

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

Überprüfen Sie dann Parameter und Ursachen mit Groovy, vergleichen Sie mit dem letzten erfolgreichen Build und starten Sie erst neu, nachdem Sie wissen, ob der Fehler am Code, an der Infrastruktur, an Anmeldeinformationen oder an Eingabeparametern lag.

Die Jenkins CLI wird nicht magisch jeden fehlgeschlagenen Build diagnostizieren. Was sie gut macht, ist Reibung zu reduzieren. Sie bringt das Log, die Metadaten und den Neustartbefehl schnell in Ihr Terminal, wo Sie suchen, vergleichen, speichern und dieselben Überprüfungen wiederholen können, wenn das nächste Mal eine Pipeline ausfällt.