Comandi Essenziali della CLI di Jenkins per la Gestione e il Controllo dei Job

La CLI di Jenkins ti aiuta a gestire i job quando l'interfaccia web è troppo lenta per lavori ripetitivi. Se devi creare job da template, avviare build o aggiornare la configurazione XML negli script, la CLI ti offre un percorso diretto.

Questa guida si concentra sui comandi di gestione dei job: list-jobs, get-job, create-job, copy-job, update-job, delete-job e build.

Configurazione della CLI di Jenkins

Prima di eseguire qualsiasi comando, devi stabilire una connessione sicura al tuo master Jenkins. Questo comporta il download del client CLI e la garanzia di un'autenticazione corretta.

1. Scaricare il jenkins-cli.jar

Il client CLI si trova tipicamente direttamente sul tuo server Jenkins a un endpoint specifico. Puoi scaricarlo usando wget o curl:

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

2. Metodi di Autenticazione

Le connessioni alla CLI di Jenkins richiedono autenticazione. Il metodo più sicuro e raccomandato è l'uso di un Token API invece di una semplice password utente.

Per generare un Token API, naviga su Impostazioni Utente > Configura > Token API nell'interfaccia web di Jenkins.

Tutti i comandi successivi richiederanno flag di autenticazione, tipicamente usando i flag -s (URL del server) e -auth (credenziali di autenticazione):

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

Suggerimento: Per sicurezza, memorizza il tuo token API in una variabile d'ambiente sicura o usa il metodo di autenticazione con chiave SSH se configurato, invece di digitarlo direttamente negli script.

Comandi Principali per la Scoperta dei Job

Prima di modificare i job, è spesso necessario elencare i job esistenti e recuperare le loro configurazioni.

Elencare Tutti i Job: list-jobs

Questo comando mostra i nomi di tutti i job configurati sul master Jenkins.

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

Recuperare la Configurazione di un Job: get-job

I job di Jenkins sono definiti da file di configurazione XML. Il comando get-job ti permette di recuperare questa definizione XML, essenziale per creare nuovi job basati su template.

# Recupera la configurazione di 'my-template-job' e salvala in un file
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

Comandi Essenziali per la Gestione dei Job

Questi comandi gestiscono le operazioni fondamentali del ciclo di vita per i job di Jenkins.

1. Creare un Nuovo Job: create-job

Il comando create-job richiede il nome del nuovo job e il file di configurazione XML che ne definisce i parametri, i passaggi di build e i trigger.

Prerequisiti: Devi prima avere un file di configurazione XML valido (es. new-config.xml), solitamente derivato modificando un template recuperato con get-job.

# Esempio: Crea un nuovo job chiamato 'project-feature-branch' usando il file XML locale
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. Copiare un Job Esistente: copy-job

Questo è spesso il modo più veloce per creare un nuovo job, prendendo un job esistente come template e applicando un nuovo nome. Questo comando duplica efficacemente la configurazione del job sorgente.

# Sintassi: copy-job NOME_JOB_SORGENTE NOME_JOB_DESTINAZIONE
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. Abilitare e Disabilitare i Job: enable-job e disable-job

Questi comandi sono cruciali per la manutenzione, le interruzioni temporanee o il controllo amministrativo, impedendo o permettendo l'avvio delle build.

# Comando per fermare ulteriori build programmate o attivate per manutenzione
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# Comando per riattivare il job
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. Eliminare un Job: delete-job

Questo comando rimuove permanentemente un job dall'istanza Jenkins, inclusa la sua cronologia delle build e la configurazione. Usa questo comando con cautela.

# Rimozione permanente del job
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

Attenzione: Il comando delete-job viene eseguito immediatamente senza ulteriore conferma nell'ambiente CLI. Assicurati che i tuoi script includano passaggi di convalida adeguati prima di eseguire questo comando.

Avviare e Monitorare le Build

Oltre alla gestione della configurazione, la CLI è spesso utilizzata per avviare build, specialmente quelle che richiedono parametri specifici.

Avviare una Build: build

Il comando build avvia una nuova build per il job specificato. Se il job è parametrizzato, puoi passare argomenti direttamente usando il flag -p.

# Avvia una build semplice, non parametrizzata
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# Avvia un job parametrizzato, passando i parametri
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

Nota: Se usi il flag -s con build, la CLI attenderà il completamento della build e riporterà lo stato di uscita. Altrimenti, il comando ritorna immediatamente dopo aver messo in coda la build.

Visualizzare lo Stato della Build: get-job e console

Anche se la CLI non offre streaming in tempo reale paragonabile all'interfaccia web, puoi controllare lo stato del job e recuperare l'output della console.

Per visualizzare l'output della console di un numero di build specifico:

# Recupera l'output della console per la build #55 di 'my-job'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

Best Practice per lo Scripting della CLI

Sfruttare la CLI di Jenkins in modo efficiente richiede l'adozione di best practice specifiche per stabilità e sicurezza:

1. Scripting e Automazione

La CLI è più utile negli script shell. Usa get-job, modifica attentamente l'XML risultante, e poi reimmetri la configurazione modificata usando create-job o update-job.

Flusso di Lavoro Esempio (Copia, Modifica e Crea):

1. Ottieni il template: get-job template-job > tmp.xml
2. Usa sed per sostituire i segnaposto (es. nome del progetto, URL del repository) in tmp.xml.
3. Crea un nuovo job: create-job new-job < tmp.xml

2. Gestione degli Aggiornamenti di Configurazione

Per aggiornare la configurazione di un job esistente usando XML dall'input standard, usa update-job. Questo è più sicuro che eliminare e ricreare il job perché preserva la cronologia delle build.

# Aggiorna 'project-a' usando un file di configurazione modificato localmente
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job project-a < updated-config.xml

3. Gestione degli Errori

Controlla sempre il codice di uscita ($?) dopo aver eseguito un comando CLI nei tuoi script. Un codice di ritorno 0 indica successo; qualsiasi codice diverso da zero segnala un errore. Questo è vitale per un'automazione robusta e il debug.

Punto Chiave

La CLI di Jenkins è uno strumento pratico per l'amministrazione ripetibile dei job. Inizia esportando l'XML del job con get-job, apporta modifiche controllate, aggiorna i job con update-job e avvia le build con build. Tieni i token API fuori dagli script e convalida i comandi distruttivi come delete-job prima che vengano eseguiti.