Vous installez le plugin Parameterized Build comme d'habitude, via l'écran de gestion des plugins. Une fois que vous avez fait cela, configurer une tâche de build paramétrée est simple. Cochez simplement l'option “Ce build a des paramètres” et cliquez sur Ajouter un paramètre pour ajouter un nouveau paramètre de tâche de build (voir Figure 10.1, “Créer une tâche de build paramétrée”). Vous pouvez ajouter des paramètres à n'importe quelle sorte de build, et vous pouvez ajouter autant de paramètres que vous voulez à une tâche de build donnée.

Pour ajouter un paramètre à votre tâche de build, sélectionnez simplement le type de paramètre dans la liste déroulante. Cela vous permettra de configurer les détails de votre paramètre (voir Figure 10.2, “Ajouter un paramètre à la tâche de build”). Vous pouvez choisir différents types de paramètres, comme des chaînes de caractères, des booléens, et des listes déroulantes. En fonction du type que vous choisissez, vous devrez entrer des valeurs de configuration légèrement différentes, mais le processus de base est le même. Tous les types de paramètres, à l'exception du paramètre Fichier, ont un nom et une description, et le plus souvent une valeur par défaut.

Dans Figure 10.3, “Ajouter un paramètre à la tâche de build”, par exemple, nous ajoutons un paramètre appelé version à une tâche de déploiement. La valeur par défaut (RELEASE) sera initialement affichée lorsque Jenkins demandera à l'utilisateur de valoriser ce paramètre, donc si l'utilisateur ne change rien, cette valeur sera utilisée.

Quand l'utilisateur démarre un build paramétré (les builds paramétrés sont très souvent démarrées manuellement), Jenkins propose une page dans laquelle l'utilisateur peut entrer une valeur pour chacun des paramètres de la tâche de build (voir Figure 10.3, “Ajouter un paramètre à la tâche de build”).

Une fois que vous avez ajouté un paramètre, vous devez configurer vos scripts de build pour l'utiliser. Bien choisir le nom du paramètre est important, parce que c'est aussi le nom de la variable que Jenkins passera comme variable d'environnement lorsqu'il lance la tâche de build. Pour illustrer cela, considérons la configuration de build très basique de Figure 10.4, “Démonstration d'un paramètre de build”, où on affiche simplement le paramètre de build en retour dans la console. Notez que, pour rendre les variables plus portables à travers différents systèmes d'exploitation, il est préférable de les mettre en majuscules.

Quand on exécute cela, on obtient les lignes suivantes dans la console :

Started by user anonymous
Building on master
[workspace] $ /bin/sh -xe /var/folders/y+/y+a+wZ-jG6WKHEm9KwnSvE+++TI/-Tmp-/
jenkins5862957776458050998.sh
+ echo Version=1.2.3
Version=1.2.3
Notifying upstream projects of job completion
Finished: SUCCESS

Vous pouvez aussi utiliser ces variables d'environnement au sein de vos scripts de build. Par exemple, dans un build Ant ou Maven, vous pouvez utiliser la propriété spéciale env pour accéder aux variables d'environnement courantes :

<target name="printversion">
  <property environment="env" />
  <echo message="${env.VERSION}"/>
</target>

Une autre option consiste à passer les paramètres au script de build comme une valeur de propriété. Ce qui suit est un exemple plus pratique d'un fichier POM de Maven. Dans cet exemple, Maven est configuré pour déployer un fichier WAR spécifique. Nous fournissons la version du fichier WAR à déployer dans la propriété target.version, qui est utilisé dans la déclaration de la dépendance, comme montré ci-dessous :

  ...
  <dependencies>
    <dependency>
      <groupId>com.wakaleo.gameoflife</groupId>
      <artifactId>gameoflife-web</artifactId>
      <type>war</type>
      <version>${target.version}</version>
    </dependency>
  </dependencies>
  <properties>
    <target.version>RELEASE</target.version>
    ...
  </properties>

Quand on invoque Maven, on passe le paramètre comme l'une des propriétés du build (voir Figure 10.5, “Ajouter un paramètre à la tâche de build Maven”). On peut ensuite utiliser un outil comme Cargo pour faire le déploiement réel — Maven téléchargera la version demandée du WAR depuis le gestionnaire de dépôt d'entreprise, et la déploiera sur un serveur d'application.

En résumé, cela montre comment il vous est possible d'intégrer des paramètres de tâches de build dans vos builds. Toutefois, en plus des bons vieux paramètres de type chaîne de caractères, il existe quelques types de paramètres plus sophistiqués, que nous regarderons dans les paragraphes suivants (voir Figure 10.6, “Différents types de paramètres sont disponibles”).

Les paramètres Mot de passe sont, comme vous pourriez vous y attendre, très similaires aux paramètres String, mis à part qu'ils sont affichés comme des champs mot de passe.

Il existe plusieurs cas où vous souhaiteriez présenter un ensemble limité d'options de paramètres. Dans un build de déploiement, vous pourriez permettre à l'utilisateur de choisir parmi un ensemble de serveurs cibles. Ou vous pourriez présenter une liste de navigateurs supportés pour une suite de tests d'acceptation. Les paramètres Choix vous permettent de définir un ensemble de valeurs qui seront affichées dans une liste déroulante (voir Figure 10.7, “Configurer un paramètre Choix”). Vous devez fournir une liste de valeurs possibles, une par ligne, en commençant par la valeur par défaut.

Les paramètres Booléen sont, comme vous vous y attendez, des paramètres qui prennent comme valeur true ou false. Ils sont présentés en tant que case à cocher.

Deux types de paramètres plus exotiques, qui se comportent un peu différemment des autres, sont les paramètres Run et les paramètres Fichier.

Les paramètres Run vous permettent de sélectionner une exécution particulière (ou un build) d'un build donné (voir Figure 10.8, “Configurer un paramètre Run”). L'utilisateur effectue une sélection à partir d'une liste de numéros d'exécution de build. L'URL correspondant à l'exécution est stockée dans le paramètre spécifié.

L'URL (qui devrait ressembler à http://jenkins.myorg.com/job/game-of-life/197/) peut être utilisée pour obtenir une information ou des artefacts d'une exécution de build. Par exemple, vous pourriez récupérer le fichier JAR ou WAR archivé lors d'un build précédent et exécuter des tests plus poussés sur celui-ci dans une tâche de build séparée. Ainsi, pour accéder au fichier WAR d'un build précédent dans un projet Maven multimodules, l'URL ressemblerait à celle-ci :

http://buildserver/job/game-of-life/197/artifact/gameoflife-web/target/
      gameoflife.war

Donc, en utilisant le paramètre configuré dans Figure 10.8, “Configurer un paramètre Run”, vous pourriez accéder au fichier WAR en utilisant l'expression suivante :

${RELEASE_BUILD}gameoflife-web/target/gameoflife.war

Les paramètres Fichier vous permettent de télétransférer un fichier dans l'espace de travail de la tâche de build, afin qu'il puisse être utilisé dans le script de build (voir Figure 10.9, “Configurer un paramètre Fichier”). Jenkins stockera le fichier à l'emplacement spécifié dans l'espace de travail du projet, où vous pouvez y accéder dans vos scripts de build. Vous pouvez utiliser la variable WORKSPACE pour faire référence au répertoire de l'espace de travail courant, afin que vous puissiez manipuler le fichier télétransferé dans Figure 10.9, “Configurer un paramètre Fichier” en utilisant l'expression ${WORKSPACE}/deploy/app.war.

Le déclenchement paramétré possède un support spécial pour Subversion, vous permettant ainsi de réaliser un build à partir d'un tag Subversion spécifique. C'est utile si vous voulez lancer un build de release en utilisant un tag généré par un build précédent. Par exemple, une tâche de build amont pourrait créer un tag d'une révision particulière. Vous pourriez aussi utiliser le processus standard de release Maven (voir Section 10.7.1, “Gestion des releases Maven avec le plugin M2Release”) pour générer une nouvelle release. Dans ce cas, un tag avec le numéro de release Maven sera automatiquement généré dans Subversion.

Cette approche est utile pour des projets qui ont besoin d'être partiellement ou entièrement reconstruits avant de pouvoir être déployés sur une plateforme donnée. Par exemple, vous pourriez avoir besoin d'exécuter le build Ant ou Maven en utilisant différentes propriétés ou profils pour différentes plateformes, afin que les fichiers de configuration spécifiques puissent être embarqués dans les WAR ou EAR déployés.

Vous pouvez configurer un build Jenkins pour qu'il s'exécute sur un tag sélectionné en utilisant le type de paramètre “List Subversion Tag” (voir Figure 10.10, “Ajouter des paramètres pour réaliser un build à partir d'un tag Subversion”). Vous devez simplement fournir l'URL du dépôt Subversion pointant sur le répertoire des tags de votre projet.

Quand vous exécuterez ce build, Jenkins proposera une liste de tags dans laquelle choisir (voir Figure 10.11, “Réaliser un build à partir d'un tag Subversion”).

Réaliser un build à partir d'un tag Git n'est pas aussi simple que de le faire à partir d'un tag Subversion, bien que vous puissisez toujours utiliser un paramètre pour indiquer quel tag utiliser. En effet, à cause de la nature même de Git, quand Jenkins obtient une copie du code source depuis Git, il clone le dépôt Git, en incluant tous les tags. Une fois que vous avez la dernière version du dépôt sur votre serveur Jenkins, vous pouvez ensuite procéder à la récupération d'une version en utilisant git checkout <tagname>.

Pour configurer cela avec Jenkins, vous devez commencer par ajouter un paramètre String à votre tâche de build (appelée RELEASE dans cet exemple — voir Figure 10.12, “Configurer un paramètre pour un tag Git”). Contrairement au support Subversion, il n'est pas possible de lister les tags Git disponibles dans une liste déroulante, les utilisateur devront donc connaître le nom du tag qu'ils veulent livrer.

Une fois que vous avez ajouté ce paramètre, vous devez faire un checkout du tag correspondant une fois que le dépôt a été cloné localement. Ainsi, si vous avez un build freestyle, la première étape du build sera un appel en ligne de commande à Git pour faire un checkout du tag référencé par le paramètre RELEASE (voir Figure 10.13, “Réaliser un build à partir d'un tag Git”). Bien sûr, un moyen plus portable de faire cela serait d'écrire un simple script Ant ou Groovy pour faire l'équivalent d'une façon plus indépendante du système d'exploitation.

Vous pouvez aussi démarrer une tâche de build paramétrée à distance, en invoquant l'URL de la tâche de build. La forme typique d'une URL de tâche de build est illustrée ci-après :

http://jenkins.acme.org/job/myjob/buildWithParameters?PARAMETER=Value

Ainsi, dans l'exemple ci-dessus, vous pourriez déclencher un build de la façon suivante :

http://jenkins.acme.org/job/parameterized-build/buildWithParameters?VERSION=1.2.3

Quand vous utilisez une URL pour démarrer une tâche de build de cette façon, rappelez-vous que les noms des paramètres sont sensibles à la casse, et que les valeurs doivent être échappées (comme n'importe quel autre paramètre HTTP). Et si vous utilisez un paramètre Run, vous devez fournir le nom de la tâche de build et le numéro d'exécution (e.g., game-of-life#197) et pas seulement le numéro d'exécution.

Enfin, il est indispensable de savoir quels paramètres ont été utilisés pour lancer un build paramétré particulier. Par exemple, dans une tâche de build de déploiement automatisé, il est utile de savoir exactement quelle version a réellement été déployée. Heureusement, Jenkins stocke ces valeurs dans l'historique de build (voir Figure 10.14, “Jenkins stocke les valeurs des paramètres utilisées pour chaque build”), afin que vous puissiez toujours retrouver un ancien build et en vérifier les paramètres.