Commandes CLI Essentielles de Jenkins pour la Gestion et le Contrôle des Tâches

La CLI Jenkins vous aide à gérer les tâches lorsque l'interface web est trop lente pour les tâches répétitives. Si vous devez créer des tâches à partir de modèles, déclencher des builds ou mettre à jour la configuration XML dans des scripts, la CLI vous offre un chemin direct.

Ce guide se concentre sur les commandes de gestion des tâches : list-jobs, get-job, create-job, copy-job, update-job, delete-job et build.

Configuration de la CLI Jenkins

Avant d'exécuter des commandes, vous devez établir une connexion sécurisée à votre maître Jenkins. Cela implique de télécharger le client CLI et de garantir une authentification appropriée.

1. Téléchargement du jenkins-cli.jar

Le client CLI se trouve généralement directement sur votre serveur Jenkins à un point d'accès spécifique. Vous pouvez le télécharger en utilisant wget ou curl :

wget http://votre-url-jenkins:8080/jnlpJars/jenkins-cli.jar
# OU en utilisant curl
curl -O http://votre-url-jenkins:8080/jnlpJars/jenkins-cli.jar

2. Méthodes d'authentification

Les connexions CLI Jenkins nécessitent une authentification. La méthode la plus sécurisée et recommandée est l'utilisation d'un jeton API au lieu d'un mot de passe utilisateur simple.

Pour générer un jeton API, naviguez vers Paramètres utilisateur > Configurer > Jeton API dans l'interface web Jenkins.

Toutes les commandes suivantes nécessiteront des indicateurs d'authentification, généralement en utilisant les indicateurs -s (URL du serveur) et -auth (informations d'authentification) :

java -jar jenkins-cli.jar -s http://votre-url-jenkins:8080 -auth NOM_UTILISATEUR:JETON_API <commande>

Astuce : Pour des raisons de sécurité, stockez votre jeton API dans une variable d'environnement sécurisée ou utilisez la méthode d'authentification par clé SSH si configurée, plutôt que de le taper directement dans les scripts.

Commandes Principales pour la Découverte des Tâches

Avant de modifier des tâches, il est souvent nécessaire de lister les tâches existantes et de récupérer leurs configurations.

Lister toutes les tâches : list-jobs

Cette commande affiche les noms de toutes les tâches configurées sur le maître Jenkins.

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

Récupérer la configuration d'une tâche : get-job

Les tâches Jenkins sont définies par des fichiers de configuration XML. La commande get-job vous permet de récupérer cette définition XML, ce qui est essentiel pour créer de nouvelles tâches basées sur des modèles.

# Récupérer la configuration de 'ma-tache-modele' et la sauvegarder dans un fichier
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job ma-tache-modele > config-modele.xml

Commandes Essentielles de Gestion des Tâches

Ces commandes gèrent les opérations fondamentales du cycle de vie des tâches Jenkins.

1. Créer une nouvelle tâche : create-job

La commande create-job nécessite le nom de la nouvelle tâche et le fichier de configuration XML définissant ses paramètres, étapes de build et déclencheurs.

Prérequis : Vous devez d'abord disposer d'un fichier de configuration XML valide (par exemple, nouvelle-config.xml), généralement dérivé en modifiant un modèle récupéré à l'aide de get-job.

# Exemple : Créer une nouvelle tâche nommée 'branche-fonctionnalite-projet' en utilisant le fichier XML local
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job branche-fonctionnalite-projet < nouvelle-config.xml

2. Copier une tâche existante : copy-job

C'est souvent le moyen le plus rapide de créer une nouvelle tâche, en prenant une tâche existante comme modèle et en appliquant un nouveau nom. Cette commande duplique effectivement la configuration de la tâche source.

# Syntaxe : copy-job NOM_TACHE_SOURCE NOM_TACHE_DESTINATION
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job pipeline-original nouveau-pipeline-dev

3. Activer et désactiver des tâches : enable-job et disable-job

Ces commandes sont cruciales pour la maintenance, les arrêts temporaires ou le contrôle administratif, empêchant ou permettant le déclenchement des builds.

# Commande pour arrêter les builds planifiés ou déclenchés supplémentaires pour maintenance
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job build-projet-heritage

# Commande pour réactiver la tâche
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job build-projet-heritage

4. Supprimer une tâche : delete-job

Cette commande supprime définitivement une tâche de l'instance Jenkins, y compris son historique de builds et sa configuration. Utilisez cette commande avec précaution.

# Suppression définitive de la tâche
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job tache-test-obsolete

Avertissement : La commande delete-job s'exécute immédiatement sans confirmation supplémentaire dans l'environnement CLI. Assurez-vous que vos scripts incluent des étapes de validation appropriées avant d'exécuter cette commande.

Déclencher et Surveiller les Builds

Au-delà de la gestion de la configuration, la CLI est fréquemment utilisée pour déclencher des builds, en particulier ceux nécessitant des paramètres spécifiques.

Déclencher un build : build

La commande build démarre un nouveau build pour la tâche spécifiée. Si la tâche est paramétrée, vous pouvez passer des arguments directement en utilisant l'indicateur -p.

# Déclencher un build simple, non paramétré
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build deploiement-nocturne

# Déclencher une tâche paramétrée, en passant des paramètres
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build test-integration -p ENVIRONNEMENT_CIBLE=staging -p NOM_BRANCHE=hotfix-123

Remarque : Si vous utilisez l'indicateur -s avec build, la CLI attendra la fin du build et signalera le statut de sortie. Sinon, la commande revient immédiatement après avoir mis le build en file d'attente.

Voir le statut du build : get-job et console

Bien que la CLI n'offre pas de streaming en temps réel comparable à l'interface web, vous pouvez vérifier le statut des tâches et récupérer la sortie console.

Pour voir la sortie console d'un numéro de build spécifique :

# Récupérer la sortie console pour le build #55 de 'ma-tache'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console ma-tache 55

Meilleures Pratiques pour les Scripts CLI

Tirer parti efficacement de la CLI Jenkins nécessite d'adopter des meilleures pratiques spécifiques pour la stabilité et la sécurité :

1. Scripts et Automatisation

La CLI est très utile dans les scripts shell. Utilisez get-job, modifiez soigneusement le XML résultant, puis réinjectez la configuration modifiée en utilisant create-job ou update-job.

Exemple de flux de travail (Copier, Modifier et Créer) :

1. Obtenir le modèle : get-job tache-modele > tmp.xml
2. Utiliser sed pour remplacer les espaces réservés (par exemple, nom du projet, URL du dépôt) dans tmp.xml.
3. Créer une nouvelle tâche : create-job nouvelle-tache < tmp.xml

2. Gestion des Mises à Jour de Configuration

Pour mettre à jour la configuration d'une tâche existante en utilisant XML depuis l'entrée standard, utilisez update-job. C'est plus sûr que de supprimer et recréer la tâche car cela préserve l'historique des builds.

# Mettre à jour 'projet-a' en utilisant un fichier de configuration modifié localement
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job projet-a < config-mise-a-jour.xml

3. Gestion des Erreurs

Vérifiez toujours le code de sortie ($?) après avoir exécuté une commande CLI dans vos scripts. Un code de retour de 0 indique un succès ; tout code non nul signale une erreur. C'est essentiel pour une automatisation robuste et le débogage.

Point Clé à Retenir

La CLI Jenkins est un outil pratique pour l'administration répétable des tâches. Commencez par exporter le XML des tâches avec get-job, effectuez des modifications contrôlées, mettez à jour les tâches avec update-job et déclenchez des builds avec build. Gardez les jetons API hors des scripts et validez les commandes destructrices comme delete-job avant de les exécuter.