Wichtige Jenkins-CLI-Befehle für Job-Verwaltung und -Steuerung

Die Jenkins-CLI hilft Ihnen, Jobs zu verwalten, wenn die Weboberfläche für wiederholte Aufgaben zu langsam ist. Wenn Sie Jobs aus Vorlagen erstellen, Builds auslösen oder XML-Konfigurationen in Skripten aktualisieren müssen, bietet Ihnen die CLI einen direkten Weg.

Dieser Leitfaden konzentriert sich auf Befehle zur Job-Verwaltung: list-jobs, get-job, create-job, copy-job, update-job, delete-job und build.

Einrichten der Jenkins-CLI

Bevor Sie Befehle ausführen, müssen Sie eine sichere Verbindung zu Ihrem Jenkins-Master herstellen. Dazu müssen Sie den CLI-Client herunterladen und eine ordnungsgemäße Authentifizierung sicherstellen.

1. Herunterladen der jenkins-cli.jar

Der CLI-Client befindet sich normalerweise direkt auf Ihrem Jenkins-Server an einem bestimmten Endpunkt. Sie können ihn mit wget oder curl herunterladen:

wget http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar
# ODER mit curl
curl -O http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar

2. Authentifizierungsmethoden

Jenkins-CLI-Verbindungen erfordern eine Authentifizierung. Die sicherste und empfohlene Methode ist die Verwendung eines API-Tokens anstelle eines einfachen Benutzerpassworts.

Um ein API-Token zu generieren, navigieren Sie in der Jenkins-Weboberfläche zu Benutzereinstellungen > Konfigurieren > API-Token.

Alle nachfolgenden Befehle erfordern Authentifizierungsflags, normalerweise die Flags -s (Server-URL) und -auth (Authentifizierungsdaten):

java -jar jenkins-cli.jar -s http://your-jenkins-url:8080 -auth BENUTZERNAME:API_TOKEN <befehl>

Tipp: Speichern Sie Ihr API-Token aus Sicherheitsgründen in einer sicheren Umgebungsvariable oder verwenden Sie die SSH-Schlüssel-Authentifizierungsmethode, falls konfiguriert, anstatt es direkt in Skripte einzugeben.

Kernbefehle zur Job-Erkennung

Bevor Sie Jobs ändern, ist es oft notwendig, vorhandene Jobs aufzulisten und ihre Konfigurationen abzurufen.

Auflisten aller Jobs: list-jobs

Dieser Befehl zeigt die Namen aller auf dem Jenkins-Master konfigurierten Jobs an.

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

Abrufen der Job-Konfiguration: get-job

Jenkins-Jobs werden durch XML-Konfigurationsdateien definiert. Der Befehl get-job ermöglicht es Ihnen, diese XML-Definition abzurufen, was für die Erstellung neuer Jobs auf Basis von Vorlagen unerlässlich ist.

# Konfiguration für 'my-template-job' abrufen und in einer Datei speichern
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

Wichtige Befehle zur Job-Verwaltung

Diese Befehle decken die grundlegenden Lebenszyklusoperationen für Jenkins-Jobs ab.

1. Erstellen eines neuen Jobs: create-job

Der Befehl create-job erfordert den Namen des neuen Jobs und die XML-Konfigurationsdatei, die seine Parameter, Build-Schritte und Trigger definiert.

Voraussetzungen: Sie müssen zunächst eine gültige XML-Konfigurationsdatei (z.B. new-config.xml) haben, die normalerweise durch Ändern einer mit get-job abgerufenen Vorlage erstellt wird.

# Beispiel: Erstellen eines neuen Jobs namens 'project-feature-branch' mit der lokalen XML-Datei
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. Kopieren eines vorhandenen Jobs: copy-job

Dies ist oft der schnellste Weg, einen neuen Job zu erstellen, indem ein vorhandener Job als Vorlage verwendet und ein neuer Name vergeben wird. Dieser Befehl dupliziert effektiv die Konfiguration des Quell-Jobs.

# Syntax: copy-job QUELL_JOB_NAME ZIEL_JOB_NAME
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. Aktivieren und Deaktivieren von Jobs: enable-job und disable-job

Diese Befehle sind entscheidend für Wartung, vorübergehende Stopps oder administrative Kontrolle, um zu verhindern oder zu erlauben, dass Builds ausgelöst werden.

# Befehl zum Stoppen weiterer geplanter oder ausgelöster Builds für Wartungsarbeiten
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# Befehl zum Reaktivieren des Jobs
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. Löschen eines Jobs: delete-job

Dieser Befehl entfernt einen Job dauerhaft aus der Jenkins-Instanz, einschließlich seiner Build-Historie und Konfiguration. Verwenden Sie diesen Befehl mit Vorsicht.

# Dauerhafte Entfernung des Jobs
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

Warnung: Der Befehl delete-job wird in der CLI-Umgebung sofort ohne weitere Bestätigung ausgeführt. Stellen Sie sicher, dass Ihre Skripte vor der Ausführung dieses Befehls geeignete Validierungsschritte enthalten.

Auslösen und Überwachen von Builds

Über die Konfigurationsverwaltung hinaus wird die CLI häufig zum Auslösen von Builds verwendet, insbesondere solchen, die bestimmte Parameter erfordern.

Auslösen eines Builds: build

Der Befehl build startet einen neuen Build für den angegebenen Job. Wenn der Job parametrisiert ist, können Sie Argumente direkt mit dem Flag -p übergeben.

# Auslösen eines einfachen, nicht parametrisierten Builds
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# Auslösen eines parametrisierten Jobs mit Übergabe von Parametern
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Hinweis: Wenn Sie das Flag -s mit build verwenden, wartet die CLI auf den Abschluss des Builds und meldet den Exit-Status. Andernfalls kehrt der Befehl sofort nach dem Einreihen des Builds zurück.

Anzeigen des Build-Status: get-job und console

Obwohl die CLI kein Echtzeit-Streaming wie die Weboberfläche bietet, können Sie den Job-Status überprüfen und die Konsolenausgabe abrufen.

Um die Konsolenausgabe einer bestimmten Build-Nummer anzuzeigen:

# Konsolenausgabe für Build #55 von 'my-job' abrufen
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

Best Practices für CLI-Scripting

Um die Jenkins-CLI effizient zu nutzen, sollten Sie bestimmte Best Practices für Stabilität und Sicherheit beachten:

1. Scripting und Automatisierung

Die CLI ist am nützlichsten in Shell-Skripten. Verwenden Sie get-job, ändern Sie das resultierende XML sorgfältig und führen Sie die geänderte Konfiguration dann mit create-job oder update-job zurück.

Beispiel-Workflow (Kopieren, Ändern und Erstellen):

1. Vorlage abrufen: get-job template-job > tmp.xml
2. Verwenden Sie sed, um Platzhalter (z.B. Projektname, Repository-URL) in tmp.xml zu ersetzen.
3. Neuen Job erstellen: create-job new-job < tmp.xml

2. Handhabung von Konfigurationsaktualisierungen

Um die Konfiguration eines vorhandenen Jobs mit XML von der Standardeingabe zu aktualisieren, verwenden Sie update-job. Dies ist sicherer als das Löschen und Neuerstellen des Jobs, da die Build-Historie erhalten bleibt.

# 'project-a' mit einer lokal geänderten Konfigurationsdatei aktualisieren
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job project-a < updated-config.xml

3. Fehlerbehandlung

Überprüfen Sie nach der Ausführung eines CLI-Befehls in Ihren Skripten immer den Exit-Code ($?). Ein Rückgabecode von 0 zeigt Erfolg an; jeder andere Code signalisiert einen Fehler. Dies ist entscheidend für eine robuste Automatisierung und Fehlersuche.

Wichtigste Erkenntnis

Die Jenkins-CLI ist ein praktisches Werkzeug für wiederholbare Job-Verwaltung. Beginnen Sie damit, Job-XML mit get-job zu exportieren, nehmen Sie kontrollierte Änderungen vor, aktualisieren Sie Jobs mit update-job und lösen Sie Builds mit build aus. Halten Sie API-Tokens aus Skripten heraus und validieren Sie destruktive Befehle wie delete-job, bevor sie ausgeführt werden.