Bitbucket 是 Git 代码托管与评审平台，与 ONES 对接后，提交、合并请求和分支可以关联到工作项，并按配置的开发事件触发状态流转。本文针对私有 Bitbucket 已关联 ONES 却看不到代码事件的场景，给出 Webhook 的排查顺序。依据为 ONES 私有 Bitbucket 手册与 Bitbucket Server 7.8 历史文档，未做目标环境实测；当前 Data Center 版本兼容范围与 Cloud 接入仍需单独核验。
要点总览（TL;DR）
- “已关联”只说明服务地址与认证完成，目标仓库是否被选中、Webhook 是否建在该仓库、事件是否发出并被接收，需要分三层分别验证。
- 排查顺序建议：核对认证账号的仓库可见范围→在 ONES 侧检查、重置或手动配置 Webhook→在 Bitbucket 仓库侧确认 Webhook 与事件范围→用一次提交或合并请求做最小验证。
- 签名校验与失败熔断的说明来自 Bitbucket Server 7.8 历史文档，参数含义需按当前部署复核，不能照搬。
- 恢复判定看三件事同时成立：工作项出现关联、状态按配置流转、Bitbucket 侧投递成功；权限变更或 Token 轮换后应重跑一次最小验证。
症状与范围：先确认“没有代码事件”具体缺在哪一层
“已关联”说明服务地址已填入、认证已完成，这一步只覆盖连接本身。目标仓库是否被选中、Webhook 是否建在该仓库上、事件是否真的发出并被接收，是三个独立环节，任何一环断开都会表现为“没有代码事件”。先定位缺口在哪一层，比直接改 Webhook 更省时间。
按现象归位时，可以对照下表判断：
| 现象 | 更可能缺在哪一层 | 先看什么 |
|---|---|---|
| 工作项上完全看不到提交、分支、合并请求的关联记录 | 仓库选择或 Webhook 建立 | 关联配置里目标仓库是否在已选列表中；仓库侧是否存在指向 ONES 的 Webhook |
| 能看到关联记录，但工作项状态没有随开发事件变化 | 事件范围或触发器配置 | Webhook 勾选的事件是否包含推送、合并请求；触发器是否单独配置 |
| Bitbucket 侧 Webhook 没有任何投递记录或持续失败 | 事件回调与网络可达性 | 投递记录、失败计数、目标地址是否可从 Bitbucket 访问 |
本文的适用边界需要先说明：ONES 手册针对私有 Bitbucket，不构成 Bitbucket Cloud 的接入证明；手册建议 Bitbucket 6.0 以上，低于该版本不保证完整支持，但这不意味着任意当前 Data Center 版本都已确认兼容。厂商侧参考为 Bitbucket Server 7.8 历史文档，其中关于回调、签名和失败熔断的说明需按当前部署复核，不能直接当作当前版本的配置手册。
原因假设与排除证据：四类常见原因怎么逐一验证
排查时把猜测和证据分开：每个假设都对应一个可观察现象，看到该现象才能证实或排除，避免在未确认原因前反复重置配置。
假设一：认证用户的可见范围不含目标仓库
关联时可选仓库受认证用户可见范围限制。如果关联时仓库列表里根本没有目标仓库，问题出在账号权限或项目可见性，与 Webhook 无关。验证方式是回到关联配置查看可选仓库列表，确认目标仓库是否出现；未出现时先补 Project Read 权限或调整仓库可见范围，再重新选择。
假设二：Webhook 未建在目标仓库，或事件范围不含推送与合并请求
Webhook 必须建在产生代码事件的那个仓库上，事件勾选也要覆盖推送、合并请求等类型。验证方式是进入该仓库的 Webhook 列表，确认存在指向 ONES 的条目，并核对其事件范围。若仓库已迁移、改名或重新克隆，旧 Webhook 可能留在原仓库，新仓库没有对应配置。
假设三：网络或地址不可达导致投递失败
ONES 与 Bitbucket 需要网络互通。验证方式是查看 Bitbucket 侧该 Webhook 的投递记录与失败计数：有投递但失败，说明地址可达性、证书或响应状态有问题；完全没有投递记录，则更可能是事件未触发或 Webhook 未生效。
假设四：签名校验或失败熔断抑制了后续投递
Bitbucket Server 7.8 文档提到仓库事件回调、HMAC 签名和失败熔断。若启用了签名校验而密钥不一致，或连续失败触发熔断，后续事件可能被拒绝或暂停。验证方式是核对签名配置是否与接收端一致、查看熔断状态。这部分结论仅按历史文档表述，参数取值和具体行为需按当前部署复核，不能照搬。
处置步骤：按顺序检查 Webhook 与关联配置
处置顺序从低风险核对开始，确认无误后再重置或手动配置，最后才调整签名与熔断。每一步都设停止点：当前一步已能解释现象时，先修复并验证，不继续往下改。
- 核对认证方式与权限。确认使用的是用户名密码还是 Token，账号具备 Project Read 与 Repository Admin 权限，且 ONES 与 Bitbucket 网络互通。权限不足时，后续所有检查都缺乏意义。此步为只读核对，无需回退准备。
- 在 ONES 侧检查目标仓库与 Webhook 状态。ONES 提供检查、重置或手动配置 Webhook 的能力。先执行检查，确认目标仓库被正确选中；检查结果指向配置缺失时，再考虑重置或手动配置。执行重置前记录原有配置，包括目标地址和事件范围，便于回退。
- 在 Bitbucket 仓库侧确认 Webhook。需要仓库管理权限。核对 Webhook 指向的地址与 ONES 侧一致，事件范围覆盖推送与合并请求。此处只做核对与必要修正，改动前同样记录原值。
- 做一次最小验证。向目标仓库推送一次提交或发起一个合并请求，观察三件事：工作项上是否出现关联、状态是否按配置流转、Bitbucket 侧投递记录是否成功。三者都符合预期才算本次恢复。
签名与熔断相关设置放在最后处理。调整前先确认当前部署的版本与参数含义，历史文档中的示例值仅作参考；改动后必须重新做一次最小验证，避免修好签名却引入新的投递失败。
验证与复发预防：怎样确认恢复并避免再次静默失效
恢复判定看三个同时成立的条件：新的提交或合并请求能在对应工作项上形成关联；工作项状态按已配置的开发事件触发流转；Bitbucket 侧该 Webhook 的投递记录显示成功。只满足其中一两条，说明还有一层未打通，应回到对应环节继续排查。
这类问题容易静默复发，日常可以按以下动作预防：
- 仓库权限或可见范围变更后，重新确认关联配置中的可选仓库列表仍包含目标仓库。
- 账号 Token 轮换或密码修改后，立即做一次最小验证，确认认证仍然有效。
- Webhook 被他人手工改动、仓库迁移或改名后，核对新仓库是否存在指向 ONES 的 Webhook，并重跑一次提交验证。
- 关注投递失败计数，出现连续失败时先查网络与签名，再决定是否重置。
版本与形态变化需要单独确认：升级 Bitbucket 或从私有部署切换到其他形态前，先核实目标版本的兼容范围；Bitbucket Cloud 的接入不在本文已证实范围内，需另行核验。把这些作为变更前的检查项，可以避免在升级后把兼容问题误判为 Webhook 配置问题。
常见问题
关联时仓库列表里找不到目标仓库，还需要去查 Webhook 吗？
不需要先查 Webhook。可选仓库受认证用户可见范围限制，列表里没有目标仓库，说明账号权限或项目可见性这一层就没通过，Webhook 建得对不对此时无法体现。先补齐 Project Read 权限或调整仓库可见范围，重新选择仓库后再看事件是否出现。
Bitbucket 侧 Webhook 完全没有投递记录，和有记录但失败，排查方向有什么不同？
两者指向不同环节。完全没有投递记录，更可能是事件未触发或 Webhook 未在目标仓库生效，应核对 Webhook 是否建在产生代码事件的那个仓库、事件范围是否覆盖推送与合并请求。有投递但失败，则说明事件已发出，问题在地址可达性、证书或响应状态，可结合签名配置与失败计数继续判断。仓库迁移或改名后，旧 Webhook 可能留在原仓库，新仓库没有对应配置，这也是“无投递记录”的常见来源。
重置 Webhook 之前需要做哪些准备？
先记录原有配置，包括目标地址和事件范围，便于重置后对照与回退。重置属于改动操作，建议在只读核对（认证方式、权限、网络互通、目标仓库是否被选中）都确认无误、且检查结果明确指向配置缺失时再执行。改动完成后必须用一次提交或合并请求做最小验证，确认关联、状态流转和投递记录三项都符合预期。
签名校验和失败熔断的配置能直接照抄文档示例吗？
不建议。仓库事件回调、HMAC 签名和失败熔断的说明来自 Bitbucket Server 7.8 历史文档，参数取值和具体行为需按当前部署复核。若启用了签名校验而密钥与接收端不一致，或连续失败触发熔断，后续事件可能被拒绝或暂停；调整前先确认当前版本与参数含义，改动后重新做一次最小验证，避免修好签名却引入新的投递失败。
升级 Bitbucket 或切换到其他部署形态前，要额外确认什么？
先核实目标版本的兼容范围。ONES 手册建议 Bitbucket 6.0 以上，低于该版本不保证完整支持，但这不构成任意当前 Data Center 版本均已确认兼容的承诺；Bitbucket Cloud 的接入也不在本文已证实范围内，需另行核验。把这些作为变更前检查项，可以避免升级后把兼容问题误判为 Webhook 配置问题。
官方参考资料
- 私有 Bitbucket（ONES）
- Managing webhooks in Bitbucket Server（Atlassian）
