如何使用Python API获取Jenkins构建失败原因（无需修改服务端配置）

核心思路 #

原生Jenkins本身没有内置返回结构化失败原因的API，在无法安装额外插件的前提下，可以通过调用原生开放的公开接口拉取构建关联信息，自定义解析得到失败原因。

可行实现方案 #

方案1：拉取构建控制台日志做关键词匹配（通用性最高） #

Jenkins原生提供纯文本控制台日志接口，无需任何额外插件支持，返回内容包含完整的构建过程输出，你可以自定义规则匹配对应失败场景：

• 接口地址格式：http://<your_jenkins_host>/job/<job_name>/<build_number>/consoleText
• 你可以根据团队常用的构建失败场景预设匹配规则，比如：
  • 代码编译错误匹配关键词compilation error、编译失败
  • 依赖拉取失败匹配关键词Could not resolve dependencies、Connection refused
  • 单元测试失败匹配关键词FAILED test、用例执行失败
  • 部署失败匹配关键词deployment failed、端口占用

方案2：Pipeline构建场景下调用工作流API直接取失败阶段信息 #

如果你的Jenkins任务是Pipeline类型，原生自带工作流查询接口，无需额外插件，可以直接拿到每个阶段的运行状态和失败关联报错，比全量解析日志效率更高：

• 接口地址格式：http://<your_jenkins_host>/job/<job_name>/<build_number>/wfapi/describe
• 返回的JSON结构中stages字段会列出所有构建阶段，找到status为FAILED的阶段，对应error字段即可拿到该阶段的直接报错信息。

方案3：拉取构建基础信息取预设的失败描述 #

如果你的团队在构建任务中配置了失败时自动填写构建描述的规则，可以直接调用构建基础信息接口获取结构化的失败原因：

• 接口地址格式：http://<your_jenkins_host>/job/<job_name>/<build_number>/api/json
• 解析返回JSON中的description字段即可直接拿到预设的失败原因。

代码示例 #

import requests

# 配置信息替换为实际值
JENKINS_HOST = "http://your-jenkins.com"
JOB_NAME = "your-job-name"
BUILD_NUMBER = "123"
USERNAME = "jenkins-username"
API_TOKEN = "your-api-token"

# 方案1示例：拉取日志匹配失败原因
resp = requests.get(
    f"{JENKINS_HOST}/job/{JOB_NAME}/{BUILD_NUMBER}/consoleText",
    auth=(USERNAME, API_TOKEN),
    timeout=30
)
resp.raise_for_status()
console_log = resp.text

failure_reason = "未知错误"
if "compilation error" in console_log or "编译失败" in console_log:
    failure_reason = "代码编译错误"
elif "Could not resolve dependencies" in console_log:
    failure_reason = "依赖包拉取失败"
elif "FAILED test" in console_log:
    failure_reason = "单元测试执行失败"

print(f"构建{BUILD_NUMBER}失败原因：{failure_reason}")

注意：所有接口请求需要携带Jenkins认证信息，推荐使用个人API Token代替密码进行认证，避免明文密码泄露风险。

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