Jenkins Job如何通过API上传XML配置文件

Jenkins Job 配置更新必须使用 PUT 方法向 /job/{JOB_NAME}/config.xml 提交合法 XML，filename 必须为 config.xml，且需携带 Jenkins-Crumb 和 Basic Auth 认证；否则返回 400/403/404。

POST 请求必须用 config.xml 作为文件名上传

Jenkins 的 Job 配置 API 不接受任意文件名，即使内容是合法 XML。如果你用 curl 或其他工具上传，Content-Disposition 中的 filename 字段**必须是 config.xml**，否则 Jenkins 会返回 400 Bad Request 或静默忽略配置更新。

• 错误示例：filename="job-config.xml" → 失败
• 正确写法：filename="config.xml"
• 路径格式为：/job/{JOB_NAME}/config.xml（注意不是 /createItem）
• 需使用 PUT 方法，不是 POST；POST 仅用于新建 job

需要先获取 CSRF token（Jenkins 2.176+ 默认启用）

未带有效 crumb 的请求会被拒绝，返回 403 No valid crumb was included in the request。不能跳过，也不能靠 Cookie 硬凑。

• 先 GET /crumbIssuer/api/json 获取 crumb 和 crumbRequestField
• 把 crumb 值作为 header 加入后续 PUT 请求，字段名就是返回的 crumbRequestField（通常是 Jenkins-Crumb）
• 认证仍需 Basic Auth（-u user:api_token），token 推荐在用户设置页生成，不用密码

完整 curl 示例：上传前确保 XML 合法且无敏感信息硬编码

curl -X PUT \
  -H "Jenkins-Crumb: abc123..." \
  -u "alice:1a2b3c4d5e6f7g8h" \
  --data-binary @./my-job-config.xml \
  -H "Content-Type: application/xml" \
  "https://jenkins.example.com/job/my-pipeline/config.xml"

注意几点：

• --data-binary 保证换行和空格不被破坏，@ 表示读取本地文件
• XML 文件里不能含未转义的 、&；建议用 Jenkins UI 导出一份原始 config.xml 当模板
• 如果 job 不存在，该请求不会自动创建，会报 404 Not Found；需先用 /createItem 创建空 job，再上传配置

Python requests 调用容易漏掉的 headers 和编码细节

用 requests.put() 时，别直接传 data=open(...)，否则可能因编码或缓冲导致 XML 解析失败。

• 务必用 open(..., "rb") 二进制模式读取
• 显式设置 headers={"Jenkins-Crumb": crumb}，不要依赖 session 自动携带
• auth=HTTPBasicAuth(user, token) 比拼接 user:pass 更安全
• 检查响应状态码：200 表示成功；但 Jenkins 有时对非法 XML 也返回 200，只是实际没生效——建议上传后立即 GET

  

  /job/xxx/config.xml 对比校验

Jenkins 对 XML 结构校验较松，但字段缺失（比如 或 根节点不存在）会导致 job 无法保存或构建失败，上传前最好用一个测试 job 先验证。