Guide to Jenkins Parameterized Builds

1. Introduction

Jenkins is one of the most popular CICD tools in use today. It enables the automation of every aspect along the software lifecycle, from building all the way to deploying.

In this tutorial, we’ll focus on one of the more powerful features of Jenkins, parameterized builds.

2. Defining Build Parameters

To begin with, a build parameter facilitates passing data into Jenkins jobs. In particular, using build parameters, we can pass a dataset of any type and content:

• Git branch name
• secret credentials
• hostnames and ports
• other configuration

Of course, any Jenkins job or pipeline can be parameterized.

2.1. Create a Parameterized Build

Of course, to create a parameterized build, we first require a new project as a job:

In this case, we make it a Pipeline:

Specifically, to parameterize, we just check the box in the General settings tab This project is parameterized:

Thus, we tell Jenkins that the current project should be able to take parameters. Now, let’s ensure the system knows what to expect by configuring

2.2. Add Parameters

To configure the possible parameters that Jenkins should consider valid and accept for a job, we click the Add Parameter button:

After that, we specify several pieces of information:

• Type: the data type for the parameter
• Name: the name identifying the parameter
• Default (for most types): an optional value for when a user doesn’t specify one
• Description: optional text that describes how the parameter is to be used

In addition to the above, some field types may have custom fields. For example, the Choice parameter has the Choices field to indicate the available options:

Indeed, a single Jenkins job or pipeline can have multiple parameters. In fact, the only restriction is that the parameter name must be unique.

2.3. Types of Parameters

Jenkins supports several parameter types by default. Let’s see a list of the most common types of parameters:

• Boolean: enable or disable a given option
• Choice: pre-defined set of strings from which a user can pick a value
• Credentials: pre-defined Jenkins credential
• File: full path to a file on the filesystem
• Multi-line String: same as String, but can also contain newline characters
• Password: similar to the Credentials type, but can also include a plain text parameter specific to the job or pipeline
• Run: an absolute URL to a single run of another job
• String: any combination of characters on a single line

In fact, we can see each in the list after pressing Add Parameter:

Notably, different plugins may add new parameter types.

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. Furthermore, one of the most common build steps is executing a Linux shell or Windows batch script.

Let’s say we have a build parameter named packageType. Inside a shell script, we can access build parameters just like any other variable from the environment using the shell syntax:

${packageType}

Of course, with batch commands, we use the native Windows syntax:

%packageType%

In addition, we can also create build steps that execute Gradle tasks or Maven goals. Similarly, both of these step types can access build parameters just like they would any other environment variable.

3.2. Pipelines

Inside a Jenkins pipeline, we can access a build parameter in different ways.

First, all build parameters are placed into a params variable. Consequently, we can access a parameter value using dot notation:

pipeline {
    agent any
    stages {
        stage('Build') {
            when {
                expression { params.jdkVersion == "14" }
            }
        }
    }
}

Furthermore, the build parameters are added to the pipeline environment. In other words, we can use the shorter shell syntax inside a step that executes a shell script:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo "${packageType}"
            }
        }
    }
}

Thus, depending on the case and preferences, we can pick either method when using parameters.

4. Setting Parameter Values

So far, we’ve seen how to define parameters and use them inside Jenkins jobs. The final step is to pass values for the parameters when we execute jobs.

4.1. Jenkins UI

Starting a job with Jenkins UI is often the easiest way to pass build parameters. All we do is log in, navigate to the job, and click the Build with Parameters link:

This process takes us to a screen that prompts for inputs to each parameter. Based on the parameter type, the way we input its value is different.

For example, String parameters show up as a plain text field, boolean parameters as a checkbox, and Choice parameters as a dropdown list:

Once we provide a value for each parameter, we just 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 the Jenkins server:

http://<JENKINS_URL>/job/<JOB_NAME>/buildWithParameters/packageType=war&jdkVersion=11&debug=true

Notably, these are POST requests. We also have to provide credentials using basic HTTP authentication.

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=true

The user can be any Jenkins user, and the apiToken is any associated API token for that user.

5. Conclusion

In this article, we learned 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 CICD pipelines.