参数化 Jenkins 构建并使用脚本

简介

在现代 CI/CD 流水线中，灵活性和自动化是关键。将数值硬编码到构建任务中会使其变得僵化且难以管理。Jenkins 允许你通过参数化构建并在构建过程中执行脚本来克服这一问题。

在本实验中，你将学习如何创建一个灵活的 Jenkins 任务。首先，你将添加参数以允许在构建时进行用户输入。接着，你将学习如何将 Shell 脚本作为构建步骤执行，将参数传递给这些脚本，并配置能够根据构建成功或失败做出响应的构建后操作。这些是创建健壮且动态的 Jenkins 自动化工作流的基本技能。

你的环境中已经运行了一个 Jenkins 实例。你可以通过打开桌面上的 Firefox 浏览器访问 Jenkins Web 界面。浏览器会自动打开 http://localhost:8080，因此无需手动输入 URL。无需登录。

创建并参数化 Freestyle 项目

在此步骤中，你将创建一个新的 Jenkins Freestyle 项目并为其添加参数。参数使你的任务具有交互性，允许你在每次触发构建时提供输入。

首先，让我们创建任务。

从桌面界面打开 Firefox 浏览器。浏览器会自动打开 http://localhost:8080，无需手动输入 URL。无需登录。
在 Jenkins 仪表板上，点击左侧菜单中的 New Item（新建任务）。
输入 parameterized-script-job 作为任务名称。
选择 Freestyle project 并点击 OK。

创建新的 Freestyle 项目

你将被带到任务的配置页面。现在，让我们添加参数。

在 General（常规）部分，勾选 This project is parameterized（此项目是参数化的）。
点击 Add Parameter（添加参数）下拉菜单并选择 String Parameter（字符串参数）。
- Name: GREETING_NAME
- Default Value: World
- Description: Enter a name to be greeted.
再次点击 Add Parameter 下拉菜单并选择 Choice Parameter（选项参数）。
- Name: ENVIRONMENT
- Choices: (每行输入一个选项)
```
DEV
STAGING
PROD
```
- Description: Select the deployment environment.

这些参数将在后续的构建步骤中使用。

配置字符串和选项参数

最后，滚动到底部并点击 Save（保存）。你将被重定向到任务的主页面，现在你会看到 Build with Parameters（参数化构建）选项，而不是“Build Now”（立即构建）。

任务页面上的参数化构建链接

添加 Shell 脚本构建步骤

在此步骤中，你将向任务的构建过程添加一个 Shell 脚本。这是执行代码编译、运行测试或部署应用程序等任务的常用方法。

导航到 Jenkins 中的 parameterized-script-job 仪表板。
点击左侧菜单中的 Configure（配置）。
向下滚动到 Build Steps（构建步骤）部分。
点击 Add build step（增加构建步骤）下拉菜单并选择 Execute shell（执行 shell）。
在 Command（命令）文本区域中，输入以下脚本。该脚本将在 Jenkins 工作空间内创建一个项目目录结构并列出其内容。

echo "--- Starting Build Step ---"
echo "Current directory:"
pwd
echo "Creating project directory structure:"
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
echo "Listing files in the project directory:"
ls -la my-app
echo "--- Build Step Finished ---"

执行 shell 构建步骤

点击 Save（保存）以应用更改。

现在，让我们运行该任务以查看脚本的实际效果。

在任务页面上，点击 Build with Parameters。
保留默认参数值并点击 Build（构建）按钮。
左侧的 Build History（构建历史）中会出现一个新的构建。点击构建编号（例如 #1）。
点击 Console Output（控制台输出）以查看日志。

你应该能看到 Shell 脚本的输出，包括文件列表。

Started by user unknown or anonymous
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/parameterized-script-job
[parameterized-script-job] $ /bin/sh -xe /tmp/jenkins....sh
+ echo --- Starting Build Step ---
--- Starting Build Step ---
+ echo Current directory:
Current directory:
+ pwd
/var/jenkins_home/workspace/parameterized-script-job
+ echo Creating project directory structure:
Creating project directory structure:
+ mkdir -p my-app
+ echo Version 1.0
+ echo Listing files in the project directory:
Listing files in the project directory:
+ ls -la my-app
total 12
drwxr-xr-x 2 jenkins jenkins 4096 ... .
drwxr-xr-x 3 jenkins jenkins 4096 ... ..
-rw-r--r-- 1 jenkins jenkins   12 ... version.txt
+ echo --- Build Step Finished ---
--- Build Step Finished ---
Finished: SUCCESS

Shell 构建步骤的控制台输出

将参数传递给 Shell 脚本

在此步骤中，你将学习如何在 Shell 脚本中使用在步骤 1 中定义的参数。Jenkins 将构建参数公开为环境变量，你可以在脚本中使用 $VARIABLE_NAME 语法访问它们。

返回 parameterized-script-job 的 Configure（配置）页面。
向下滚动到 Build Steps 部分，找到 Execute shell 命令框。
将现有脚本替换为以下内容：

echo "--- Starting Parameterized Build Step ---"
echo "Hello, $GREETING_NAME!"
echo "Deploying to the $ENVIRONMENT environment."

## Create project structure if not exists and read the version from the file
mkdir -p my-app
echo "Version 1.0" > my-app/version.txt
APP_VERSION=$(cat my-app/version.txt)
echo "Application version is: $APP_VERSION"
echo "--- Parameterized Build Step Finished ---"

注意 $GREETING_NAME 和 $ENVIRONMENT 是如何直接在 echo 命令中使用的。当任务运行时，Jenkins 会将它们替换为用户选择的值。

点击 Save（保存）。

现在，让我们使用自定义参数运行构建。

点击 Build with Parameters。
将 GREETING_NAME 修改为 LabEx。
从 ENVIRONMENT 下拉菜单中选择 STAGING。
点击 Build。
检查新构建的 Console Output。

输出现在应该反映你提供的自定义值。

显示自定义参数值的控制台输出

--- Starting Parameterized Build Step ---
+ echo Hello, LabEx!
Hello, LabEx!
+ echo Deploying to the STAGING environment.
Deploying to the STAGING environment.
+ mkdir -p my-app
+ echo Version 1.0
+ cat my-app/version.txt
+ APP_VERSION=Version 1.0
+ echo Application version is: Version 1.0
Application version is: Version 1.0
+ echo --- Parameterized Build Step Finished ---
--- Parameterized Build Step Finished ---

使用 Shell 条件处理构建失败

在此步骤中，你将直接在 Shell 脚本中模拟构建失败。这是一种在违反部署规则时使 Freestyle 任务停止的可靠方法。

修改脚本以模拟失败

现在，让我们修改脚本，使其在特定条件下失败。

进入 parameterized-script-job 的 Configure（配置）页面。
在 Execute shell 命令框中，将脚本替换为以下内容：

echo "Deploying to the $ENVIRONMENT environment."

if [ "$ENVIRONMENT" = "PROD" ]; then
  echo "Error: Production deployment is not allowed!"
  echo "Failure handled by shell condition."
  exit 1
fi

echo "Deployment to $ENVIRONMENT was successful."

该脚本会检查 ENVIRONMENT 参数。如果设置为 PROD，它将打印错误并以状态码 1 退出。在 Shell 脚本中，任何非零的退出码都会向 Jenkins 发出失败信号。

点击 Save（保存）。

测试失败条件

现在，让我们测试失败条件。

点击 Build with Parameters。
为 ENVIRONMENT 选择 PROD 并点击 Build。
构建将失败，构建历史记录中会显示一个红色图标。
检查 Console Output。你将看到来自脚本的错误消息以及最终的 Jenkins 构建状态。

显示构建失败的控制台输出

Deploying to the PROD environment.
+ [ PROD = PROD ]
+ echo Error: Production deployment is not allowed!
Error: Production deployment is not allowed!
+ echo Failure handled by shell condition.
Failure handled by shell condition.
+ exit 1
Build step 'Execute shell' marked build as failure
Finished: FAILURE

如果你再次使用 DEV 或 STAGING 运行构建，它将会成功，因为失败条件未被触发。

总结

恭喜你！你已经成功创建了一个灵活且健壮的 Jenkins 任务。

在本实验中，你学习了如何：

使用字符串和选项参数创建参数化的 Jenkins 任务。
将 Shell 脚本作为构建过程的一部分执行。
在脚本中将构建参数作为环境变量进行访问和使用。
在脚本中实现条件逻辑以控制构建结果。
使用 Shell 条件和退出码来控制构建是成功还是失败。

这些技能对于构建能够适应不同输入并智能处理错误的复杂 CI/CD 流水线至关重要。现在，你可以将这些概念应用到自己的开发和部署工作流自动化中。

参数化构建与脚本使用

简介