jenkins

用途

Jenkins Skill 用于通过 Groovy Script Console API 管理 Jenkins CI 服务器。适用场景包括：用户希望检查构建状态、更新流水线、触发构建或查看日志。当用户提到 Jenkins、CI 构建、部署流水线或构建状态时，可激活该技能。

所有脚本路径均相对于本技能的基础目录。

配置

首次使用前，先检查 ~/.config/jenkins.json 是否存在：

python3 scripts/jenkins_api.py check-config

如果配置缺失，向用户询问以下信息：

Jenkins URL（例如 http://jenkins.example.com:8080）
用户名（具有 Script Console 访问权限的 Jenkins 用户）
API Token（在 Jenkins → User → Configure → API Token 中生成）

然后保存配置：

python3 scripts/jenkins_api.py init --url '<URL>' --user '<USER>' --token '<TOKEN>'

脚本会在保存前验证连接。如果失败，报告错误并请用户检查凭据。

架构

凭据存储在 ~/.config/jenkins.json（位于任何仓库之外）：

{
  "url": "http://your-jenkins:8080",
  "user": "your-username",
  "token": "your-api-token"
}

重要：如果用户缺少 Job/Configure 权限，config.xml REST API（POST）可能无法工作。本技能使用 Groovy Script Console API（POST /scriptText），它只需要 Script Console 访问权限。

使用方式

运行 CLI 辅助工具执行常见操作：

python3 scripts/jenkins_api.py <command> [args...]

命令列表：

list（无参数）：列出所有 Jenkins 任务
status <job_name>：获取最近一次构建状态
trigger <job_name>：触发一次新构建
log <job_name>：获取控制台日志（最后 200 行）
script <job_name>：获取内联流水线脚本
groovy <script>：在 Script Console 上运行任意 Groovy

示例：

# 检查构建状态
python3 scripts/jenkins_api.py status my-job

# 触发构建
python3 scripts/jenkins_api.py trigger my-job

# 查看构建日志
python3 scripts/jenkins_api.py log my-job

# 获取流水线脚本
python3 scripts/jenkins_api.py script my-job

# 运行自定义 Groovy
python3 scripts/jenkins_api.py groovy 'println Jenkins.instance.allItems*.fullName'

修改流水线脚本

要以编程方式更新内联流水线脚本，可通过 run_groovy() 使用 Groovy Script Console。示例：

from scripts.jenkins_api import run_groovy

result = run_groovy("""
import jenkins.model.Jenkins
import org.jenkinsci.plugins.workflow.job.WorkflowJob
import org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition

def job = Jenkins.instance.getItemByFullName("my-job") as WorkflowJob
def oldScript = ((CpsFlowDefinition) job.definition).script
def newScript = oldScript.replace("old text", "new text")
job.definition = new CpsFlowDefinition(newScript, false)
job.save()
println "Done"
""")

重要：脚本安全审批。当设置 CpsFlowDefinition(script, false)（禁用沙箱）时，Jenkins 要求脚本在运行前由管理员审批。在审批前，下一次构建会因 UnapprovedUsageException 失败。

要在修改流水线后自动审批待处理脚本：

run_groovy("""
import org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval
def sa = ScriptApproval.get()
sa.pendingScripts.each { ps ->
    sa.approveScript(ps.hash)
    println "Approved: ${ps.hash}"
}
""")

修改任何流水线脚本后，请始终立即运行此审批步骤。

修改 FreeStyleProject 构建步骤

FreeStyleProject 任务（非流水线）需要不同方法。要添加/修改构建步骤：

run_groovy("""
import jenkins.model.Jenkins
import hudson.tasks.Shell

def job = Jenkins.instance.getItemByFullName("my-freestyle-job")
def builders = job.buildersList
def existing = builders.toList()

def newStep = new Shell("#!/usr/bin/env zsh\\nsource ~/.zshrc\\nmy-command")

builders.clear()
builders.add(existing[0])  // 保留第一个步骤（例如 EnvInject）
builders.add(newStep)       // 插入新步骤
builders.add(existing[1])  // 保留原始构建步骤
job.save()
""")

网络说明

如果 Jenkins 域名被 ICP 合规屏蔽（在中国云提供商中较常见），脚本会在 _load_config() 中通过正则将主机名解析为 IP。如需要，可在 jenkins_api.py 中配置主机名到 IP 的映射。

技能介绍

用途

配置

架构

使用方式

修改流水线脚本

修改 FreeStyleProject 构建步骤

网络说明