4.4 Webhooks 与 GitHub

Webhooks 让外部平台和 banz 互相通知：GitHub 上有人请求你审查、合并了代码、CI 失败了，banz 把这件事变成一张卡片，送到相关的人的收件箱或群聊里；反过来，也可以把 banz 里的事（比如主题有变化、会话在等人处理）发到飞书群或你自己的地址。要动手配置的是组织的所有者和管理员，以及能修改项目的人；其他成员只需要连接一次自己的 GitHub 账号。

能做什么

方向	能接的平台	效果
入站	GitHub、通用（“提供方”里的 `generic`）	外部事件变成卡片，按规则发给点到的人、主题参与者或群聊
出站	飞书（feishu）、通用（`generic`）	banz 里的事件发到你填的目标地址

GitHub 事件有两种接法：

GitHub App：组织在 GitHub 上安装一次，所有绑定的仓库都能收事件，GitHub 那边不用逐个仓库设置，也不用管地址和凭据。私有仓库的卡片发给个人时，只发给 GitHub 允许读这个仓库的人。推荐用这种。
手动：每个仓库在 GitHub 的设置里自己填 banz 给的接收地址和签名凭据。

先要配好什么

谁	做什么	多久做一次	看哪一节
组织所有者或管理员	在组织页把 GitHub App 的安装关联到组织，批准成员的连接申请	每个组织一次	下面“组织管理员：关联 GitHub App”
每位成员	在“设置”→“账号”的“已连接的账号”里点“连接 GitHub”（本机工作台和服务器网页都有），验证自己的 GitHub 账号，GitHub App 才能把点名到他的卡片发给他	每人一次	无
能修改项目的人	绑定仓库，建入站 Webhook，写规则	每个项目一次	下面“建入站 Webhook”和“写规则：卡片发给谁”

用 GitHub App 时，默认接收拉取请求、审查、议题、议题评论、推送、分支和标签的创建与删除、CI 运行（workflow_run、workflow_job）和发布。

组织管理员：关联 GitHub App

你自己是 GitHub 组织的管理员时：

打开组织页，找到“关联”。
点“在 GitHub 上安装”，在 GitHub 上选要安装到的组织和仓库（全部仓库或指定仓库），确认。已经装过的点“选择已有的安装”。
回到组织页，“关联”里出现这个安装，状态是“正常”，并写着覆盖全部仓库还是指定仓库，以及事件是“已授予”还是“仍在申请”。

安装只在持续通过验证时才投递：关联它的人必须仍是该组织在 GitHub 上的管理员。不需要了点“断开”，它会立即停止投递，之后可以重新关联。

成员替组织申请：GitHub 组织的管理员在 banz 里只是普通成员时，他在组织页的“连接申请”里点“申请关联”，选他掌管的安装。所有者或管理员在“连接申请”里查看后点“批准”或“拒绝”，也可以屏蔽申请人。申请 14 天没人处理就过期。

个人仓库：想让个人项目收自己 GitHub 账号下仓库的事件，打开个人项目“设置”标签里的“Webhooks”，在“你的 GitHub 安装”里点“在 GitHub 上安装”或“选择已有的安装”，不需要别人批准。前提是先在“设置”→“账号”的“已连接的账号”里连接了 GitHub 账号。关联之前，“来源”里的“GitHub App”是灰的，提示“请先关联上方的安装”。

建入站 Webhook

顺序是先绑仓库，再建 Webhook。规则只能在已绑定的仓库里挑，不能超出它们。

在项目页的“仓库”标签绑定仓库（见 4.1 项目）。
打开项目页的“设置”标签，找到“Webhooks”。只有能修改项目的人能看到这一块，而且要登录。
填“名称”，“方向”选“入站”，“提供方”选 github。
“来源”：选“GitHub App”就不用填别的；选“手动（自有地址与凭据）”时，点“在本地生成签名凭据”，复制保存好。
点“创建 Webhook”。

用“手动”来源时，还要到 GitHub 仓库的设置里加一个 Webhook：地址填 banz 显示的“接收地址”：它是完整网址，点旁边的“复制”即可。密钥填刚才生成的签名凭据。

已经有手动 GitHub Webhook 的项目可以点“转换为 GitHub App”：原来的地址立即失效，规则和还没关闭的卡片保留。这一步不能撤销。

写规则：卡片发给谁

没有规则时什么都不会发。在 Webhook 详情的“规则”里点“添加规则”，每条规则选：

启用：停用的规则保留，但不生效。
事件：“全部事件（常用卡片）”（banz 有专门样式的卡片）、“全部 GitHub 事件”（这个安装已获批准的每个事件的每个动作）、某个事件的全部动作（例如“issues：所有动作”），或某一种 GitHub 事件。下拉里显示的是事件名，例如 pull_request.review_requested（请求审查）、pull_request.closed.merged（合并）、workflow_run.completed.failure（CI 失败）。
仓库：“Project 绑定的全部仓库”（即这个项目绑定的全部仓库），或指定一个仓库。
发给谁（可以多选）：
- “消息里点到的人”：比如被请求审查的人、被指派的人；
- “Subject 参与者”（即主题参与者）：发给某个主题的参与者；
- “群”：发到组织里的群聊，例如“官网改版小组”；
- “GitHub 登录名”：指定几个 GitHub 账号，逗号分隔。

改完点“保存规则”。熟悉格式的人可以点“高级：编辑 JSON”直接改。

几条限制：

发到群的卡片由组织机器人发，机器人要先在群里：先在组织页建机器人，再把它加进群。个人项目不能发到群。
GitHub App 的私有仓库卡片直接发到规则选的群；发给个人时，只发给 GitHub 允许读这个仓库的人。手动 Webhook 判断不了仓库是否公开，卡片会发给规则点名的人。
被点名的人没在 banz 里验证 GitHub 账号时，GitHub App 不会发给他。

查看和维护

在 Webhook 详情里：

已启用 / 已停用：用开关停用后不再接收。
最近入站投递：每次投递的结果：待处理、已投递、已忽略、失败、结果不确定。“已忽略”会写原因，例如“连接未覆盖此仓库”“被点名的人尚未在 banz 中验证 GitHub 账号”。改了规则后，可以点“按当前规则重新评估”让被忽略的投递再走一遍。
仓库覆盖（GitHub App 来源）：哪些已绑定的仓库被安装覆盖了，没覆盖的不会收到事件。
写入 / 替换凭据（手动来源）：换签名凭据。入站有两个凭据槽，可以先写入新的槽，到 GitHub 上换成新凭据，再点“退役此槽”停用旧的，中间不断。

出站：把 banz 的事件发出去

在“Webhooks”里，“方向”选“出站”，“提供方”选 feishu（飞书群机器人）或 generic（你自己的地址）。
填“完整目标 URL（只写）”，需要签名时填签名凭据。
点“创建 Webhook”。
在详情的“出站订阅（每行一个）”里写要发出去的事件，保存。可选的有：
- subject.created、subject.changed：主题新建、主题有变化；subject.* 表示主题的所有事件；
- session.needs_you.*：会话在等人处理，也可以只订其中一种：session.needs_you.opened、session.needs_you.answered、session.needs_you.expired、session.needs_you.cancelled、session.needs_you.removed；
- hook.event.received：收到了一条入站事件。

收件箱和群聊里的卡片

规则命中后，收件箱里出现一条，来源写“Webhook 事件”，原因写“外部事件”。卡片上是一句话说清发生了什么，例如“周明请求审查首页导航重构”“陈思远合并了价格页样式调整”，旁边标着级别（提示、正常、需要关注、有问题）和来源（GitHub）。群聊里显示同样的卡片。