The creation of a parameterized Jenkins build is one of the easiest ways to add flexibility and customization to your continuous integration pipelines. In this parameterized Jenkins build example, see how easy it is to create and configure a CI job that you customize for each run.
The option to create a parameterized Jenkins build job is a core feature of the popular CI tool, so you don't need to install any plug-ins to create one. In the second part of this tutorial, we will extend the parameterized Jenkins build job example and use the Jenkins Git integration plug-in to pull from GitHub. This isn't a requirement of the first part of this tutorial, though.
Create a freestyle parameterized build example
In step one of this parameterized Jenkins build job example, create a new freestyle project, and name it parameterized-build example.
Once you've created the build job, Jenkins will display the item's configuration page. On this configuration page, there is an unselected checkbox next to text that states: "This project is parameterized." Select this option, and in the drop-down that subsequently appears, choose the option to add a Boolean parameter.
Name the Boolean parameter generate_javadoc, and enable the Default Value checkbox.
Click the Add Parameter drop-down list a second time, and choose to create a String parameter. Name this Jenkins build parameter javadoc_location and give it a default value of C:\javadoc.
Execute the build step
The next step in this parameterized Jenkins build example is to add a build step that simply echoes these values back to the console. To do so, scroll down toward the bottom of the parameterized-build-job configuration page, click the Add build step drop-down box, and choose the Execute Windows batch command option.
In the text input area that appears, just above the link to the Jenkins environment variables list, enter the following text:
# Parameterized Jenkins build job example
Save the build job, and choose the option to Build with Parameters. Accept the defaults, and click the Build button. The default values should be echoed in the console output.
Change the default values, and run the parameterized Jenkins build example once again. Notice how the updated values are echoed in the console output.
Let the program generate Javadoc
To use the variables in a more meaningful way, this Jenkins parameterized build example will incorporate Git, GitHub and the Java Development Kit's (JDK) Javadoc utility. The first portion of this Jenkins parameterized build example had no prerequisites other than a working Jenkins installation. The remainder of this Jenkins tutorial requires the Git plug-in and the JDK's bin directory on the computer's system path.
In another Jenkins Git integration tutorial, we pulled a Java project from GitHub and generated Javadoc for all of the source files with the following command:
dir /s /b *.java > file.lst
javadoc -d C:\_javadoc @file.lst
We will now expand upon this script and incorporate Jenkins build parameters. This will provide the program with a choice to generate Javadoc or not and, if generated, where it'll be located.
To pull Java source code from a GitHub repository, simply click the Git radio button in the Source Code Management section of the build job's configuration page, and enter the following GitHub URL in as the Git location: github.com/cameronmcnz/rock-paper-scissors.git.
Once the Git repository is configured, move back to the build script, and update it with the following code:
#Jenkins Parameterized Build Example
if "%generate_javadoc%"=="true" (
dir /s /b *.java >file.lst
javadoc -d %javadoc_location% @file.lst
Save the build, and run the parameterized Jenkins build example again by clicking on the Build Job with Parameters option. Notice that, when the job runs, the program will use the input the user provided to decide whether to generate Javadoc or not and, if so, where that Javadoc should be stored.
And that's it. This Jenkins parameterized build example demonstrates just how easy it is to integrate runtime parameters and customize your CI pipelines.