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 focus on 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 need to do is check the box on the General settings tab, “This project is parameterized”:

jenkins parameterized builds enable checkbox

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 identifying the parameter
  • Default value: an optional value that will be used when a user doesn’t 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 that 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, we can access a build paramater 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 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:

jenkins build with parameters

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 as a checkbox, and Choice parameters as a dropdown list:

jenkins build with parameters example

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

Note that we have to send these requests as a 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=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 CI/CD pipelines.

Comments are closed on this article!