Zulip Bitbucket 集成指南将 Bitbucket Cloud 仓库事件实时同步到 Zulip【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulipBitbucket Cloud 集成是 Zulip 内置的官方 Webhook 之一用于把 Bitbucket 仓库中的 push、Pull Request、Issue、Fork、提交评论、构建状态变更等事件实时转发到 Zulip 的指定频道支持 Git 与 Mercurial 两种仓库类型。本指南将基于 zerver/webhooks/bitbucket/doc.md 完整讲解从 Zulip 侧创建机器人、生成带分支过滤的 Webhook URL到 Bitbucket 仓库侧配置触发器与保存的端到端流程并结合仓库源码深入剖析事件类型识别、主题Topic命名规则、分支过滤逻辑与静默提及等底层实现帮助你独立完成集成配置并能按需扩展消息样式。集成概览与适用范围Bitbucket CloudAtlassian 云托管版通过向 Zulip 的公开 Webhook 端点推送 JSON 负载Payload实现仓库事件到 Zulip 消息的自动转换。整个集成的核心入口是 zerver/webhooks/bitbucket/view.py 中的api_bitbucket_webhook视图函数它通过webhook_view(Bitbucket2, all_event_typesALL_EVENT_TYPES)装饰器注册并在 zerver/lib/integrations.py 中登记了历史兼容名称bitbucket2因此早期的bitbucket2URL 依然可用测试用例test_legacy_urls专门验证了这一点。需要特别区分的是本文档描述的Bitbucket CloudSaaS 版与Bitbucket Data Center / Server自托管版走的是两套不同的集成后者的 Webhook 负载格式与事件键不同需参见 Bitbucket Data Center 集成。配置时请务必确认你的仓库类型避免选错集成。第一步在 Zulip 中创建 Incoming Webhook 机器人在 Zulip 组织内进入组织设置创建一个Incoming webhook类型的机器人通常命名为Bitbucket系统会为该机器人生成一条专属的 Webhook URL。该 URL 是所有 Bitbucket 通知的目标地址形如https://你的 Zulip 服务器域名/api/v1/external/bitbucket2?api_key机器人的 API Keystream目标频道名URL 中bitbucket2是 Zulip 内部为 Bitbucket Cloud 集成注册的端点名称见 zerver/lib/integrations.py 的legacy_names[bitbucket2]即使改名后旧端点也保持兼容。通过 URL 参数实现分支过滤Zulip 允许在 Webhook URL 上追加branches参数实现按分支过滤 push 通知。例如只关注master与development两个分支的推送https://你的 Zulip 服务器域名/api/v1/external/bitbucket2?api_keyKeystreambitbucketbranchesmaster,development该参数在 view.py 中被声明为可选的branches: str | None Nonepush 事件到达后会调用is_branch_name_notifiable(branch, branches)定义于 zerver/lib/webhooks/git.py进行匹配不在列表内的分支推送将被静默忽略、不发送任何消息但响应仍是 200 成功。测试用例test_push_event_filtered_by_branches_ignore通过MagicMock断言了check_send_webhook_message未被调用从侧面验证了这一行为。注意分支过滤仅作用于 push 事件Pull Request、Issue 等其他类型事件不受branches参数影响。第二步在 Bitbucket 仓库侧配置 Webhook进入目标仓库页面按以下步骤操作对应 doc.md 的第 3、4 步点击仓库导航栏中的Settings设置在左侧菜单选择Webhooks点击Add webhook添加 Webhook在Title标题一栏填写任意便于识别的名称例如Zulip将第一步生成并追加了branches参数的 URL 填入URL一栏勾选Active复选框使 Webhook 处于激活状态在Triggers触发器中选择你希望接收通知的事件类型点击Save保存完成配置。保存后可以回到 Bitbucket 的 Webhook 列表页点击该 Webhook 的“查看近期投递View recent deliveries”来排查是否成功送达。配置完成后任何触发事件都会在 Zulip 目标频道中产生对应的通知消息效果参见下方截图。支持的事件类型与触发场景集成共注册了 17 种事件类型ALL_EVENT_TYPES见 view.py覆盖 Bitbucket 仓库协作的主流场景事件类型触发场景push分支/标签推送、删除分支、强推force pushfork仓库被 forkcommit_comment在提交上添加评论change_commit_status构建/CI 状态变更如 SUCCESSFUL、FAILEDissue_created/issue_updated/issue_commentedIssue 创建、更新、评论pull_request_created/pull_request_updatedPR 创建、更新pull_request_approved/pull_request_unapprovedPR 被批准 / 撤销批准pull_request_fulfilled/pull_request_rejectedPR 被合并 / 被拒绝pull_request_comment_created/pull_request_comment_updated/pull_request_comment_deletedPR 评论的增删改repo:updated仓库元信息变更名称、描述、语言、主页等其中 PR 相关的动作集合被显式声明为PULL_REQUEST_SUPPORTED_ACTIONSview.py并依赖 Bitbucket 的X-Event-KeyHTTP 请求头来区分如pullrequest:approved、pullrequest:rejected。get_type函数view.py展示了事件判定策略push / fork / commit_comment / commit_status / issue / pullrequest 均优先从 JSON 负载结构推断例如负载中存在push键即判定为 push 事件只有 PR 事件与repo:updated需要读取X-Event-Key请求头若两者都无法识别则抛出UnsupportedWebhookEventTypeError记录不支持的事件。push 事件的细分处理push 事件是信息量最大的一类get_push_bodies 对 Bitbucket 负载中push.changes数组逐条解析并分派普通分支推送get_normal_push_body汇总 commit 列表作者、短 SHA、提交链接、消息调用通用get_push_commits_event_messagezerver/lib/webhooks/git.py生成“N commits to branch xxx附提交明细”的消息多个作者时还会按“Commits by Ben (2) and Tomasz (1)”的方式统计强推force pushget_force_push_body提示目标分支与最新提交 hash删除分支当change[new]为空时判定为分支删除get_remove_branch_push_body输出“xxx deleted branch xxx.”标签推送/删除get_push_tag_body依据new/old判断标签是“pushed”还是“removed”超过显示上限当 Bitbucket 标记truncated为 true提交数超限时消息末尾追加[and more commit(s)]测试见push_commits_above_limit用例。Bitbucket 的单次 Webhook 可能同时携带多个变更如同时推送分支与标签集成会为每个 change 生成独立的 Zulip 消息测试用例test_more_than_one_push_event与test_push_more_than_one_tag_event分别验证了多条消息的生成顺序与各自主题。主题Topic命名规则Zulip 的主题命名由 view.py 中的三个模板决定可在配置后根据频道中的消息主题快速区分事件来源与对象模板格式示例来自测试常量仓库名fork、标签、仓库更新、提交评论、CI 状态{repository_name}Repository name分支推送{repo} / {branch}Repository name / masterPR / Issue{repo} / {type} #{id} {title}Repository name / PR #1 new commit、Repository name / issue #1 Bug这些格式由 zerver/lib/webhooks/git.py 的TOPIC_WITH_BRANCH_TEMPLATE与TOPIC_WITH_PR_OR_ISSUE_INFO_TEMPLATE定义。此外你也可以在 Webhook URL 上追加topic自定义主题参数强制覆盖主题user_specified_topic参数此时消息正文会额外带上 PR/Issue 的标题信息include_titleTrue测试用例test_issue_created_with_custom_topic_in_url、test_pull_request_created_with_custom_topic_in_url均验证了该行为。用户识别与静默提及Silent Mentions这是本集成的一个特色能力。自 Atlassian 推行 GDPR 合规调整后Bitbucket Cloud 的 Webhook 负载中不再提供username字段而是返回account_id、display_name、nickname三字段。集成据此实现了用户映射get_user_info若负载中存在account_id且你的 Zulip 组织为成员配置了Atlassian Cloud 账户 ID的自定义字段custom profile field集成会通过guess_zulip_user_from_external_account匹配到对应 Zulip 用户并使用静默提及语法_**用户名|用户ID**生成提及——被提及者会收到通知但消息不会显示 提及的文本避免打断阅读见 doc.md 的提示框以及如何获取 Atlassian account ID 的官方说明链接无法匹配时退化为display_name再退化为nickname全部缺失时输出Unknown user并记录一条“unsupported event”日志消息仍会发送。测试用例test_push_event_message_silent_mention完整演示了该链路先在zuliprealm 添加atlassian自定义字段、为hamlet用户填入测试account_id再断言 push 消息中出现了_**Hamlet|id**的静默提及语法test_get_user_info则验证了字段缺失时的逐级回退逻辑。源码架构与验证测试消息构建的分发机制除 push 外其余事件统一走“按类型查表”的分发方式GET_SINGLE_MESSAGE_BODY_DEPENDING_ON_TYPE_MAPPERview.py将每种事件类型映射到对应的消息构建函数其中 PR/Issue 的“created/updated/approved/rejected”等动作通过functools.partial预绑定动作词复用同一构建函数最终统一交给zerver.lib.webhooks.common.check_send_webhook_message发送并开启unquote_url_parametersTrue以还原 URL 中的转义字符。仓库更新事件repo:updated则遍历website / name / links / language / full_name / description六个字段逐个比较新旧值生成“xxx changed the xxx of the repo from xxx to xxx”的逐行消息。测试覆盖zerver/webhooks/bitbucket/tests.py 提供了一套完整的回归测试BitbucketHookTests除上文已提及的用例还覆盖了多作者 push 的提交统计与“others”折叠分支过滤命中 / 未命中branchesmaster,development与brancheschanges,development两方向行为负载中无changes的 push 事件直接返回成功、不产生消息test_push_without_changes_ignore每个事件类型的期望消息文本expected_message常量即集成消息格式的权威样例可作为调试 Webhook 时核对输出格式的参考。运行与调试提示集成是 Zulip 服务端的内置功能无需安装额外依赖。本地开发环境可通过./tools/run-dev启动开发服务器后用以下命令模拟一次 push 负载投递来验证链路注意替换机器人与 URLcurl -X POST \ https://localhost:9991/api/v1/external/bitbucket2?api_key你的API Keystreambitbucket \ -H Content-Type: application/json \ -H X-Event-Key: repo:push \ --data-binary zerver/webhooks/bitbucket/fixtures/push.jsonzerver/webhooks/bitbucket/fixtures/目录存放了所有事件类型的真实负载样例push、force_push、fork、issue_created、pull_request_approved_or_unapproved 等 22 个 JSON 文件既可用于手工调试也是理解负载字段结构的最佳参考。常见问题Webhook 保存后测试无消息先在 Bitbucket 的 Webhook 投递记录中确认请求是否成功到达若 404检查 URL 中的端点名是否为bitbucket2及 API Key 是否正确若 200 但无消息检查branches参数是否把目标分支过滤掉了以及是否选择了正确的接收频道。分不清 Cloud 与 Data Center两者 Webhook 负载格式不同Data Center 请改用 bitbucketdatacenter 集成切勿混用。消息中用户名为 “Unknown user”通常是负载缺失display_name/nickname且account_id未能匹配到 Zulip 自定义字段请确认组织内atlassian自定义字段已正确维护。事件未通知Bitbucket 侧 Trigger 中未勾选对应事件类型或该事件类型不在ALL_EVENT_TYPES支持范围内例如 branch 权限变更类事件后者会在服务端日志中记录为 unsupported event。相关文档Webhook URL 规范与通用配置说明webhooks-url-specificationURL 的stream、topic、branches等查询参数约定事件过滤与分支过滤的扩展用法见 doc.md 中的 event-filtering 附加说明入站 Webhook 机器人创建与消息格式通用指南zerver/lib/integrations.py 的机器人注册与 URL 构建逻辑Bitbucket 负载样例目录zerver/webhooks/bitbucket/fixtures/【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考