1. Introduction
Jenkins is one of the most popular CI/CD tools in use today. It allows us to automate every aspect of the software lifecycle, from building all the way to deploying.
In this tutorial, we'll look at one of the more powerful features of Jenkins: parameterized builds.
2. Defining Build Parameters
A build parameter allows us to pass data into our Jenkins jobs. Using build parameters, we can pass any data we want: git branch name, secret credentials, hostnames and ports, and so on.
Any Jenkins job or pipeline can be parameterized. All we have to do is check the box on the General settings tab that says This project is parameterized:
Then we click the Add Parameter button. From here, we must specify several pieces of information:
- Type: the data type for the parameter (string, boolean, etc.)
- Name: the name by which the parameter will be identified
- Default value: an optional value that will be used when a user does not specify one
- Description: optional text that describes how the parameter is used
A single Jenkins job or pipeline can have multiple parameters. The only restriction is the parameter name must be unique.
2.1. Types of Parameters
Jenkins supports several parameter types. Below is a list of the most common ones, but keep in mind that different plugins may add new parameter types:
- String: any combination of characters and numbers
- Choice: a pre-defined set of strings from which a user can pick a value
- Credentials: a pre-defined Jenkins credential
- File: the full path to a file on the filesystem
- Multi-line String: same as String, but allows newline characters
- Password: similar to the Credentials type, but allows us to pass a plain text parameter specific to the job or pipeline
- Run: an absolute URL to a single run of another job
3. Using Build Parameters
Once we've defined one or more parameters, the next step is to utilize them. Below, we'll look at different ways to access parameter values.
3.1. Traditional Jobs
With a traditional Jenkins job, we define one or more build steps. The most common build step is executing a shell script or Windows batch commands.
Let's say we have a build parameter named packageType. Inside a shell script, we can access build parameters just like any other environment variable using the shell syntax:
${packageType}And with batch commands, we use the native Windows syntax:
%packageType%We can also create build steps that execute Gradle tasks or Maven goals. Both of these step types can access build parameters just like they would any other environment variable.
3.2. Pipelines
Inside a Jenkins Pipeline, accessing a build parameter can be done in multiple ways.
First, all build parameters are placed into a params variable. This means we can access a parameter value using dot notation:
pipeline {
agent any
stages {
stage('Build') {
when {
expression { params.jdkVersion == "14" }
}
}
}
}Second, the build parameters are added to the environment of the pipeline. This means we can use the shorter shell syntax inside a step that executes a shell script:
pipeline {
agent any
stages {
stage('Build') {
steps {
echo "${packageType}"
}
}
}
}4. Setting Parameter Values
So far, we've seen how to define parameters and use them inside our Jenkins jobs. The final step is to pass values for our parameters when we execute jobs.
4.1. Jenkins UI
Starting a job with the Jenkins UI is the easiest way to pass build parameters. All we do is log in, navigate to our job, and click the Build with Parameters link:
This will take us to a screen that asks for inputs for each parameter. Based on the type of parameter, the way we input its value will be different.
For example, String parameters will show up as a plain text field. Boolean parameters will be displayed as a checkbox. And Choice parameters are displayed as a dropdown list:
Once we provide a value for each parameter, all we have to do is click the Build button, and Jenkins begins executing the job.
4.2. Remote Execution
Jenkins jobs can also be executed with a remote API call. We do this by calling a special URL for the job on our Jenkins server:
http://<JENKINS_URL>/job/<JOB_NAME>/buildWithParameters/packageType=war&jdkVersion=11&debug=trueNote that these requests have to be sent as POST command. We also have to provide credentials using HTTP basic auth.
Let's see a full example using curl:
curl -X POST --user user:apiToken \
http://<JENKINS_URL>/job/<JOB_NAME>/buildWithParameters/packageType=war&jdkVersion=11&debug=trueThe user can be any Jenkins user, and the apiToken is any associated API token for that user.
5. Conclusion
In this article, we've seen how to use build parameters with both Jenkins jobs and pipelines. Build parameters are a powerful way to make any Jenkins job dynamic and are essential to building modern CI/CD pipelines.
The post Guide to Jenkins Parameterized Builds first appeared on Baeldung.
