Jenkins CLI 必备命令：作业管理与控制

当 Web UI 对于重复性工作过于缓慢时，Jenkins CLI 可帮助您管理作业。如果您需要从模板创建作业、触发构建或在脚本中更新 XML 配置，CLI 提供了一条直接路径。

本指南重点介绍作业管理命令：list-jobs、get-job、create-job、copy-job、update-job、delete-job 和 build。

设置 Jenkins CLI

在执行任何命令之前，您必须与 Jenkins 主节点建立安全连接。这包括下载 CLI 客户端并确保正确的身份验证。

1. 下载 jenkins-cli.jar

CLI 客户端通常位于 Jenkins 服务器的特定端点上。您可以使用 wget 或 curl 下载：

wget http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar
# 或使用 curl
curl -O http://your-jenkins-url:8080/jnlpJars/jenkins-cli.jar

2. 身份验证方法

Jenkins CLI 连接需要身份验证。最安全且推荐的方法是使用 API 令牌，而不是明文用户密码。

要生成 API 令牌，请在 Jenkins Web UI 中导航至 用户设置 > 配置 > API 令牌。

所有后续命令都需要身份验证标志，通常使用 -s（服务器 URL）和 -auth（身份验证凭据）标志：

java -jar jenkins-cli.jar -s http://your-jenkins-url:8080 -auth USERNAME:API_TOKEN <command>

提示： 为了安全，请将 API 令牌存储在安全的环境变量中，或使用已配置的 SSH 密钥身份验证方法，而不是直接将其输入到脚本中。

作业发现的核心命令

在修改作业之前，通常需要列出现有作业并检索其配置。

列出所有作业：list-jobs

此命令显示 Jenkins 主节点上配置的所有作业的名称。

java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH list-jobs

检索作业配置：get-job

Jenkins 作业由 XML 配置文件定义。get-job 命令允许您检索此 XML 定义，这对于基于模板创建新作业至关重要。

# 检索 'my-template-job' 的配置并保存到文件
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH get-job my-template-job > template-config.xml

基本作业管理命令

这些命令处理 Jenkins 作业的基本生命周期操作。

1. 创建新作业：create-job

create-job 命令需要新作业的名称以及定义其参数、构建步骤和触发器的 XML 配置文件。

先决条件： 您必须首先拥有一个有效的 XML 配置文件（例如 new-config.xml），通常通过修改使用 get-job 检索的模板获得。

# 示例：使用本地 XML 文件创建名为 'project-feature-branch' 的新作业
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH create-job project-feature-branch < new-config.xml

2. 复制现有作业：copy-job

这通常是创建新作业最快的方法，以现有作业为模板并应用新名称。此命令有效地复制源作业的配置。

# 语法：copy-job SOURCE_JOB_NAME DESTINATION_JOB_NAME
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH copy-job original-pipeline new-dev-pipeline

3. 启用和禁用作业：enable-job 和 disable-job

这些命令对于维护、临时暂停或管理控制至关重要，可防止或允许触发构建。

# 停止进一步计划或触发的构建以进行维护
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH disable-job legacy-project-build

# 重新激活作业
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH enable-job legacy-project-build

4. 删除作业：delete-job

此命令从 Jenkins 实例中永久删除作业，包括其构建历史和配置。请谨慎使用此命令。

# 永久删除作业
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH delete-job obsolete-test-job

警告： delete-job 命令在 CLI 环境中立即执行，无需进一步确认。确保您的脚本在执行此命令之前包含适当的验证步骤。

触发和监控构建

除了配置管理之外，CLI 还经常用于触发构建，尤其是那些需要特定参数的构建。

触发构建：build

build 命令为指定作业启动新构建。如果作业是参数化的，您可以使用 -p 标志直接传递参数。

# 触发一个简单的、非参数化的构建
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build nightly-deploy

# 触发参数化作业，传递参数
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH build integration-test -p TARGET_ENV=staging -p BRANCH_NAME=hotfix-123

注意： 如果您在 build 中使用 -s 标志，CLI 将等待构建完成并报告退出状态。否则，该命令在将构建排队后立即返回。

查看构建状态：get-job 和 console

虽然 CLI 不提供与 Web UI 相当的实时流式传输，但您可以检查作业状态并检索控制台输出。

要查看特定构建号的控制台输出：

# 检索 'my-job' 构建 #55 的控制台输出
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH console my-job 55

CLI 脚本的最佳实践

高效利用 Jenkins CLI 需要采用特定的最佳实践以确保稳定性和安全性：

1. 脚本编写和自动化

CLI 在 shell 脚本中最有用。使用 get-job，仔细修改生成的 XML，然后将修改后的配置通过 create-job 或 update-job 反馈回去。

示例工作流程（复制、修改和创建）：

1. 获取模板：get-job template-job > tmp.xml
2. 使用 sed 替换 tmp.xml 中的占位符（例如项目名称、仓库 URL）。
3. 创建新作业：create-job new-job < tmp.xml

2. 处理配置更新

要使用标准输入的 XML 更新现有作业的配置，请使用 update-job。这比删除并重新创建作业更安全，因为它保留了构建历史。

# 使用本地修改的配置文件更新 'project-a'
java -jar jenkins-cli.jar -s $JENKINS_URL -auth $AUTH update-job project-a < updated-config.xml

3. 错误处理

在脚本中执行 CLI 命令后，始终检查退出码（$?）。返回码 0 表示成功；任何非零码表示错误。这对于稳健的自动化和调试至关重要。

关键要点

Jenkins CLI 是用于可重复作业管理的实用工具。首先使用 get-job 导出作业 XML，进行受控更改，使用 update-job 更新作业，并使用 build 触发构建。将 API 令牌保留在脚本之外，并在运行之前验证像 delete-job 这样的破坏性命令。