jenkins-rest-ops

jenkins-rest-ops

概述

这项技能让 Agent 通过直接使用 curl 调用远程访问 REST API 来执行 Jenkins CI/CD 操作——无需 SDK，也不依赖 pip。Jenkins 采用路径寻址：在几乎任何对象的 URL 后追加 api/json 即可读取对象；向操作路径发送 POST 请求即可写入。Agent 使用调用方注入的凭据，在随附索引中查找 CORE 路径，构造 curl 命令并解析 JSON。它涵盖可行的 CORE 功能范围——触发、轮询、状态、控制台、列表，以及任务 CRUD 和构建管理——并刻意限定在 Jenkins API 范围内（不会向仓库提交 Jenkinsfile，也不会配置 SCM Webhook；这些属于 vcs 操作）。Jenkins 没有官方 OpenAPI，因此 CORE 路径以官方远程访问文档为依据。

何时启用

• ✅ 触发构建（build / buildWithParameters）并跟踪其结果。
• ✅ 读取构建状态（result / building / duration）或控制台日志。
• ✅ 列出 / 检查任务、队列、节点和视图。
• ✅ 通过 Jenkins API 执行任务 CRUD——创建（createItem + config.xml）、复制、删除、启用 / 禁用——以及构建管理（停止 / 删除构建）。

以下情况请勿启用：

• 你需要将 Jenkinsfile / 流水线配置提交到仓库，或配置 SCM Webhook 将仓库指向 Jenkins——这些属于 vcs 操作（GitHub/GitLab/Bitbucket 操作技能），而非 Jenkins API 操作。（通过 createItem 创建 Jenkins 任务属于适用范围；向仓库提交流水线源码则不属于。）
• 你只需要设置凭据——凭据由调用方提供；这项技能不会创建或解析凭据（见 references/credentials.md）。
• 操作依赖插件提供的端点——CORE API 与插件无关；插件端点因安装环境而异，不属于保证支持的范围。

工作流

步骤 1 — 接收注入的凭据

调用方已解析账户并注入此操作所需的信息——请使用这些信息；不要自行查找记录。你会从上下文中收到：

• base_url、username 和功能权限（cicd）——作为上下文值提供，而不是从文件中读取。
• 令牌，按有序加载规则获取：上下文会提供其变量名称；若项目级 .env 文件存在且定义了该变量，则使用其中的值，否则使用同名的环境变量（优先读取项目 .env）。令牌的值不会出现在上下文说明中——只有变量名称；curl 会从环境中读取该值。不要执行任何作用域解析或目录遍历来查找 .env；这里指的是项目 .env，而不是 .envrc。

将这些信息映射到脚本固定使用的变量 base_url / username / JENKINS_TOKEN。身份验证使用 HTTP Basic：curl -u "$username:$JENKINS_TOKEN"。完整约定见：references/credentials.md。

步骤 2 — 查找路径

查阅 assets/endpoint-index.md——这是依据官方远程访问文档整理的权威 CORE 路径表。Jenkins 采用路径寻址，因此路径是模板（job/<name>/build），适用于所有任务。对于随附的（非官方）swaggy-jenkins 规范也有描述的那部分接口，可运行 python3 scripts/endpoint.py <operationId> 输出其请求 / 响应架构，以作交叉核对（关于其仅用于交叉核对的原因，见 references/patterns.md）。

步骤 3 — 构造并运行 curl

应用 references/patterns.md 中的模式：

• 身份验证： 每次调用都使用 -u "$username:$JENKINS_TOKEN"。
• 读取： GET <base_url>/<path>/api/json；使用 ?tree=field[sub] 缩小响应。只要 ?tree= 中包含 [方括号]，就传入 curl -g（--globoff）——它们是 curl 的 glob 元字符，否则会导致请求中止并报错 "bad range"（curl 错误 3）。
• 写入： POST。使用令牌身份验证时不需要 crumb（令牌不受 CSRF 限制）。仅当出现 403 No valid crumb 时才添加 -H "$(bash scripts/crumb.sh)"。
• 文件夹： 每一层嵌套都重复使用 job/；对 job 名称进行 URL 编码。

随附的 scripts/*.sh（trigger-build、poll-queue-item、build-status、console-log、list-jobs、crumb）是可参考的示例。

步骤 4 — 对于构建，遵循异步流程

触发构建是异步的——它返回的是队列项，而不是构建：

1. trigger-build.sh <job> [K=V …] → 输出队列项 URL（Location 标头）。
2. poll-queue-item.sh <queue-item-url> → 轮询直到构建启动，并输出构建 URL + 编号。
3. 使用 build-status.sh <job> [<n>] 获取 result/building，使用 console-log.sh <job> [<n>] 获取日志。

队列项解析完成前，切勿读取构建编号——构建仍可能在队列中。

步骤 5 — 处理响应

• 读取会返回 JSON（当 building 为 true 时，result 为 null）。使用 ?tree= 避免载荷过大；?depth=N 会很快使载荷膨胀。
• 错误： POST 出现 403 No valid crumb 表示需要添加 crumb（步骤 3）；crumbIssuer 返回 404 表示 CSRF 已关闭（不需要 crumb）；其他情况下出现 401/403 表示令牌错误或已过期，或者权限不足。

规则

硬性规则（绝不违反）：

• 不使用 SDK，不使用 pip。 API 调用使用 curl；唯一的辅助工具是 scripts/endpoint.py（仅使用 python3 标准库）。
• 绝不读取或打印令牌值。 只在 curl -u 参数中以 $JENKINS_TOKEN 的形式引用它；子进程会从环境变量中读取它。令牌只存在于 .env（已加入 gitignore）或环境变量中。
• 触发构建会返回队列项，而不是构建。 在读取构建状态前，始终轮询直至可执行 queue/item/<id>/api/json。
• 令牌身份验证不需要 crumb。 不要在每次 POST 时都盲目获取并附加 crumb；仅在出现 403 No valid crumb 时将其作为后备措施附加。
• 依据 CORE 索引，而非 swaggy-jenkins。 使用 assets/endpoint-index.md（基于官方资料）获取路径；随附的 swaggy-jenkins 规范只是非官方且不完整的交叉参考，绝不能作为事实依据。
• 遵循 Jenkins API。 不要提交 Jenkinsfile 或配置 SCM webhook——这些属于 vcs 操作。
• 此技能绝不写入凭据。 凭据由调用方提供。

偏好（可覆盖）：

• 优先使用 ?tree= 选择字段，而非 ?depth=N，以缩小响应。
• 优先使用每位用户的 API token，而非登录密码（官方文档不建议使用密码）。
• 对已完成的构建使用 consoleText；对正在运行的构建，使用 logText/progressiveText?start=<offset> 流式获取日志。

易错点

• 异步构建陷阱。 构建 POST 会返回 201 + Location: 队列项，而不是构建编号。立即读取 job/<name>/lastBuild 可能会得到之前的构建。应先轮询队列项，直到出现 .executable。
• 队列项的短暂有效性。 队列项仅在构建结束后约 5 分钟内有效——请及时轮询并捕获 .executable.url。
• Crumb 混淆。 使用当前版本的 Jenkins 和 API 令牌时，不需要 crumb（自 2.96/2.107 起，令牌认证豁免）。403 No valid crumb 表示 Jenkins 版本较旧或使用了密码认证 → 此时再获取 crumb。对 crumbIssuer/api/json 返回 404 表示 CSRF 已禁用 → 跳过即可。
• config.xml 的 Content-Type。 createItem 要求请求正文以 Content-Type: application/xml 发送（使用 --data-binary @config.xml），否则 XML 会被错误地当作表单处理。
• 文件夹嵌套。 文件夹内的任务路径为 job/<folder>/job/<name>——每一层都要重复 job/；job/<folder>/<name> 是错误的。
• buildWithParameters 需要参数化任务。 只有任务声明了参数，这些参数才会生效；未参数化的任务会忽略它们。请先在任务配置中定义参数。
• 参数化任务会拒绝 /build 并返回 400 Bad Request。 与上面相反：任务一旦声明了参数，POST job/<name>/build 就会返回 400——必须使用 buildWithParameters（即使要使用已声明的默认值且不发送任何覆盖值也是如此）。因此，不带任何 K=V 参数的 trigger-build.sh <job>（它会向 /build 发送请求）无法触发参数化任务；请至少传入一个 K=V（或一个默认值），以便请求转到 buildWithParameters。
• swaggy-jenkins 不完整且有些古怪。 随附的规范遗漏了 buildWithParameters、consoleText、任意的 job/<n>/<build>/api/json，还为 postJobBuild 建模了一个虚构的 json 查询参数。路径应以 assets/endpoint-index.md 为准。
• 构建期间 result 为 null。 仍在运行的构建会报告 building: true、result: null——不要将 null 视为失败。
• 轮询超时表示“仍在队列中”，而不是“失败”。 poll-queue-item.sh 会在约 3 分钟后放弃；若构建因无可用执行器、静默期、.blocked 或 .stuck 而合法地受阻，也会触发超时，但并不代表构建失败。请检查 .why 并重新轮询——不要误报失败。
• 响应过大。 忙碌实例上不带 ?tree=/?depth= 的 api/json 响应可能很大；务必进行筛选。

反模式

• 轮询队列前就读取构建。 这是最常见的失败原因——触发操作返回的是队列项，而不是构建。请先轮询。
• 每个 POST 都附加 crumb。 在令牌认证下这样做既浪费又不妥（令牌认证可豁免）；只在收到 403 时获取 crumb，并处理已禁用时返回 404 的情况。
• 将 swaggy-jenkins 当作权威来源。 它不是官方规范且不完整——仅用于交叉核对。CORE 索引才是事实来源。
• 回显令牌。 切勿执行 echo $JENKINS_TOKEN，切勿将令牌粘贴到会被打印的命令中，也切勿将其值写入文件。仅在 curl -u 中引用环境变量。
• 提交 Jenkinsfile / 配置 Webhook。 这是 vcs 操作，而非 Jenkins API 操作——不在范围内。
• SDK 膨胀。 不要转而使用基于 jar 的 Jenkins CLI 或 pip 客户端——curl 和索引已覆盖 CORE 范围。

输出

此技能会产生API 副作用（执行请求的 Jenkins 操作），并将解析后的 JSON（或纯文本控制台日志）返回给调用方 Agent。它不会自行写入任何文件（只会使用调用方注入的凭据）。对于构建，它会报告队列项 → 构建 URL/编号 → 最终 result；对于读取操作，则返回请求的 JSON。抽象调用方是需要执行 CI/CD 操作的调用方 Agent（或子 Agent）；机密信息绝不会出现在输出中。

相关内容

• references/credentials.md — 本技能使用的凭据契约（调用方注入的 base_url + username + 有序的令牌加载规则 + HTTP-Basic 桥接）。
• references/patterns.md — 异步构建流程、crumb 回退、路径/文件夹/响应整形、状态与控制台、作业 CRUD，以及缺少官方 OpenAPI 依据的注意事项。
• REST 直连 + 捆绑规范这一模式可推广到其他 API 提供方（相同的 curl 驱动 REST 操作形式，适配 Jenkins 基于路径的 API + HTTP-Basic 令牌认证）。

渐进式披露

较大的内容位于子文件夹中，仅按需加载：

• references/credentials.md — 调用方注入的字段、有序的令牌加载规则、HTTP-Basic 桥接、诚实处理密钥。在步骤 1 中加载。
• references/patterns.md — 异步构建 + 队列轮询、crumb 回退、路径/文件夹/?tree=、状态与控制台、作业 CRUD、依据注意事项。在步骤 3–5 中加载。
• references/sources.md — 来源信息（官方 Remote Access 文档 + 非官方 swaggy-jenkins 标记）+ “需确认实时信息”的条目。
• assets/endpoint-index.md — 权威的 CORE 路径表（步骤 2）。
• assets/swaggy-jenkins-openapi.json — 捆绑的非官方 OpenAPI（通过解析器查询，绝不整体加载；用于部分交叉核验）。
• scripts/endpoint.py + .validation.md — 基于 swaggy-jenkins 的 python3 解析器（步骤 2 交叉核验）。
• scripts/{trigger-build,poll-queue-item,build-status,console-log,list-jobs,crumb}.sh + .validation.md — 六个经过验证的示例脚本。

独立使用（可选，非必需）

这是为 在 Agent 流程之外手动运行本技能的人类 提供的便利方式，不是本技能的依赖项。本技能的规范契约是调用方注入（步骤 1）；本附录仅用于手动操作桥接。

如需手动运行，请创建 API 令牌（<base_url>/me/configure → API Token → Add new token），将其值存入已加入 gitignore 的 .env，然后自行填写这三个变量：

set -a; source .env; set +a                 # loads $JENKINS_CI_TOKEN, never prints it
export base_url="https://jenkins.example.com"
export username="my-user"
export JENKINS_TOKEN="$JENKINS_CI_TOKEN"
bash scripts/list-jobs.sh                    # verify auth
q="$(bash scripts/trigger-build.sh my-job BRANCH=main)"
bash scripts/poll-queue-item.sh "$q"

令牌值仅通过名称引用，绝不会打印。Jenkins 令牌拥有完整的用户权限（无作用域）——建议优先使用可撤销的令牌。

正文长度限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌 — 每轮都会保留在上下文中；REST 详情位于 references/ 中。
• assets/swaggy-jenkins-openapi.json 文件较大（在磁盘上查询，绝不加载到上下文中）。