如何通过REST API手动设置Jenkins构建的自定义触发原因

原生实现方案（无需额外安装插件） #

使用user:apiToken格式认证调用/build POST接口时，直接在请求体中携带cause参数即可替换默认的「Started by user xxxx」触发原因，不需要开启「Trigger builds remotely (e.g., from scripts)」选项也能生效。

curl请求示例 #

curl -X POST "http://<你的Jenkins域名/IP地址>/job/<目标任务名>/build" \
  --user <你的用户名>:<对应用户的apiToken> \
  --data-urlencode "cause=自定义触发原因，例如：CI自动化脚本触发v1.2.0版本灰度构建"

如果是带构建参数的任务，调用/buildWithParameters接口即可，cause参数和其他业务构建参数放在同一层级提交就行。

注：该原生特性兼容Jenkins 2.289及以上的LTS版本，更低版本可自行测试兼容性。

插件替代方案 #

如果你的Jenkins版本不支持原生cause参数，可以安装Custom Build Cause Plugin实现需求：

• 插件安装完成后会扩展Jenkins的构建触发接口能力，支持传入自定义的触发原因文本，还可以额外配置触发原因关联的跳转链接、标识图标等扩展内容，完全替换默认的用户触发提示。

额外使用提示 #

如果需要在构建过程中读取你传入的自定义触发原因：

• 自由风格任务可以直接读取BUILD_CAUSE环境变量取值
• Pipeline任务可以通过currentBuild.getBuildCauses()[0].shortDescription获取到自定义的原因内容

内容的提问来源于stack exchange，提问作者Finlay