Bitbucket：如何通过REST API检查提交的构建状态？

我之前也碰到过完全一样的困扰！用Bitbucket v1 API做自动PR合并时，总是因为合并检查里的Jenkins构建没完成而失败，找API文档找了好久才摸到门道。下面是我实测有效的方法：

核心思路 #

Bitbucket v1 API的构建状态接口是绑定到提交哈希的，你需要先拿到PR对应的head commit哈希，再通过这个哈希查询关联的构建状态，等状态符合要求后再执行合并操作。

具体步骤 #

1. 获取PR的Head Commit哈希
   先调用PR详情接口拿到你发起的PR的最新提交哈希：

   GET /rest/api/1.0/projects/{项目Key}/repos/{仓库Slug}/pull-requests/{PR ID}
   

   返回的JSON里，fromRef.latestCommit字段就是你需要的commit哈希值。

2. 查询该Commit的构建状态
   用上面拿到的哈希调用构建状态接口：

   GET /rest/build-status/1.0/commits/{commitHash}
   

   返回的结果是一个包含多个构建状态的数组，每个状态项里的关键字段：

   • state: 构建状态，可选值有INPROGRESS（构建中）、SUCCESSFUL（构建完成且成功）、FAILED（构建失败）等
   • key: 构建标识，一般Jenkins推送的状态会带有Jenkins任务名相关的key，比如jenkins-my-job，你可以通过这个过滤出你需要关注的那个Jenkins构建

3. 循环等待构建完成
   在你的脚本里加入循环逻辑：

   • 每隔30-60秒调用一次构建状态接口
   • 过滤出Jenkins对应的构建状态
   • 当状态变为SUCCESSFUL时，再执行PR合并的API调用

注意事项 #

• 确保你的API账号拥有REPO_READ和BUILD_STATUS_READ权限，否则会返回403
• 刚触发Jenkins构建时，Bitbucket可能还没同步到状态，第一次查询可能返回空数组，这时候不要直接判定失败，多等一会儿再查
• 如果你的合并检查允许构建失败后合并（不推荐），可以把判断条件改成state != INPROGRESS

很多开发者在用v1 API做自动化PR流程时都遇到过这个问题，主要是因为v1的文档把构建状态接口放在了比较隐蔽的位置，不像v2那么直观。按上面的步骤来，应该就能解决你的合并失败问题了。

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