Guide to Jenkins Parameterized Builds – Jenkins参数化构建指南

最后修改: 2020年 10月 17日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.绪论

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.

Jenkins是当今最流行的CI/CD工具之一。它使我们能够自动处理软件生命周期的每一个方面，从构建一直到部署。

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

在本教程中，我们将重点介绍Jenkins的一个更强大的功能–参数化构建。

2. Defining Build Parameters

2.定义构建参数

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.

构建参数允许我们在Jenkins作业中传递数据。使用构建参数，我们可以传递任何我们想要的数据：git分支名称、秘密凭证、主机名和端口，等等。

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作业或pipeline都可以被参数化。我们需要做的就是在常规设置选项卡上勾选”本项目已被参数化”。

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.

一个Jenkins作业或管道可以有多个参数。唯一的限制是，参数名称必须是唯一的。

2.1. Types of Parameters

2.1.参数的类型

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:

Jenkins支持几种参数类型。下面是一个最常见的列表，但请记住，不同的插件可能会增加新的参数类型。

  • 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

3.使用构建参数

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

3.1.传统工作

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.

在传统的Jenkins作业中，我们定义一个或多个构建步骤。最常见的构建步骤是执行一个shell脚本或Windows批处理命令。

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的构建参数。在shell脚本中，我们可以像其他环境变量一样使用shell语法访问构建参数。

${packageType}

And with batch commands, we use the native Windows syntax:

而对于批处理命令，我们使用本地的Windows语法。

%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.

我们还可以创建执行Gradle任务或Maven目标的构建步骤。这两种类型的步骤都可以访问构建参数，就像访问其他环境变量一样。

3.2. Pipelines

3.2 管线

Inside a Jenkins Pipeline, we can access a build paramater in multiple ways.

在Jenkins Pipeline中，我们可以通过多种方式访问构建参数。

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

首先，所有的构建参数都被放入一个params变量。这意味着我们可以使用点符号来访问一个参数值。

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:

其次，构建参数被添加到管道的环境中。这意味着我们可以在执行shell脚本的步骤中使用更短的shell语法。

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

4. Setting Parameter Values

4.设置参数值

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.

到目前为止，我们已经看到如何定义参数并在我们的Jenkins作业中使用它们。最后一步是在我们执行作业时为我们的参数传递值。

4.1. Jenkins UI

4.1 Jenkins用户界面

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 UI启动一个作业是传递构建参数的最简单方法。我们所做的就是登录，导航到我们的作业，然后点击带参数构建链接。

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:

例如，String参数将显示为纯文本字段，boolean参数为复选框，而Choice参数为下拉列表。

Once we provide a value for each parameter, all we have to do is click the Build button, and Jenkins begins executing the job.

一旦我们为每个参数提供了一个值，我们所要做的就是点击Build按钮，Jenkins就开始执行作业。

4.2. Remote Execution

4.2.远程执行

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:

Jenkins作业也可以通过远程API调用来执行。我们通过在我们的Jenkins服务器上为作业调用一个特殊的URL来实现这一点。

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.

注意，我们必须以POST命令的形式发送这些请求。我们还必须使用HTTP basic auth提供凭证。

Let’s see a full example using curl:

让我们看看一个使用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.

user可以是任何Jenkins用户，而apiToken是该用户的任何相关API token。

5. Conclusion

5.总结

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.

在这篇文章中，我们学习了如何在Jenkins作业和管道中使用构建参数。构建参数是使任何Jenkins作业动态化的强大方式，也是构建现代CI/CD管道的关键。