Jenkins指南参数化构建 | Baeldung中文网

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

Note 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=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'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.

Persistence

REST

Security