GitHub Meta API 新增 Webhook 网段后白名单应怎样维护

GitHub 在 2026 年 10 月 29 日的 Changelog 中宣布，Meta API 的 hooks 字段新增了三段用于 GitHub.com Webhook 投递的 CIDR。维护静态网络白名单的团队需要把它们加入现有规则，否则接收端可能在网络层直接拒收新来源；如果白名单本来就定期读取 Meta API，则不需要手工追加。

官方公告：https://github.blog/changelog/2026-10-29-webhook-ip-ranges-added-to-the-meta-api/

Meta API：https://api.github.com/meta

先判断白名单是手工维护还是自动同步

这次变更最容易漏掉的地方，不是 CIDR 本身，而是团队不清楚白名单到底由谁维护。GitHub 官方说明，如果接收服务保存的是固定列表，就要把三段新增网段与原有 hooks 地址并列加入；如果服务已经从 Meta API 更新列表，则继续按原流程读取即可。

建议先在配置仓库、基础设施代码和部署脚本中搜索 hooks、allowlist 或旧的 GitHub 地址，确认修改入口。不要只在防火墙控制台临时加一条规则，否则下次发布或策略同步时可能被覆盖。

静态白名单怎样安全追加三段 CIDR

静态列表适合变更频率低、网络策略由发布流程统一管理的团队。追加时保留旧规则，先做格式和重复检查，再生成新文件并执行平滑加载。下面的命令只演示维护思路，实际的重载命令要替换成你们使用的防火墙、反向代理或云安全组工具。

#!/usr/bin/env bash
set -euo pipefail

# 将 GitHub 公告中的新增网段作为配置输入，保留旧列表以便回滚。
allowlist_file="/etc/webhook/github-hooks.allow"
backup_file="${allowlist_file}.bak"
tmp_file="${allowlist_file}.next"

cp "$allowlist_file" "$backup_file"
cat > "$tmp_file"  "${tmp_file}.clean"
mv "${tmp_file}.clean" "$tmp_file"

# 原子替换配置；这里的 reload 要换成接收服务支持的平滑加载命令。
mv "$tmp_file" "$allowlist_file"
systemctl reload webhook-receiver

这里的关键是“追加而不是替换”。公告只说明了新增范围，并没有要求删除既有 hooks 网段。若服务使用云安全组或 WAF，应该把相同的变更放进对应的 IaC 或发布流程，保证配置仓库、边界设备和应用接收端的状态一致。

动态同步时以 Meta API 的 hooks 字段为准

动态方案不应把公告中的三段 CIDR 永久硬编码，而是定期读取当前 Meta API 响应中的 hooks 数组。GitHub 文档明确提醒，Meta API 返回的是当前值，文档中的示例地址不能当作最新列表。更新程序可以把拉取、校验、写入和重载拆成独立阶段：

# 读取 GitHub 当前的 Webhook 来源范围，只取 hooks 字段。
curl -fsSL https://api.github.com/meta | jq -r '.hooks[]' > /var/lib/webhook/github-hooks.next

# 变更前确认文件非空，再原子替换，避免短暂得到空白名单。
test -s /var/lib/webhook/github-hooks.next
mv /var/lib/webhook/github-hooks.next /var/lib/webhook/github-hooks.current

# 让接收端重新载入已更新的来源范围。
systemctl reload webhook-receiver

生产实现还应加入超时、失败保留旧文件、响应格式检查和变更审计。拉取失败时宁可继续使用上一份有效列表，也不要用空响应覆盖当前策略。对高敏感环境，可以把新旧 CIDR 先做差异记录，待人工确认后再推送边界设备。

白名单更新后还要保留哪些接收端防护

IP allowlist 只能缩小“哪些网络来源可以到达服务”的范围，不能证明请求内容没有被篡改，也不能保证处理逻辑正确。GitHub 的 Webhook 最佳实践仍包括使用高熵 secret、启用 HTTPS 和证书校验、检查 X-GitHub-Event 与 payload 的 action，并在 10 秒内返回 2XX。

因此发布检查可以按四层记录：网络层确认三段 CIDR 已进入有效策略；传输层确认 HTTPS 校验没有被关闭；应用层验证签名、事件类型和幂等键；运行层确认接收接口快速应答，耗时处理交给队列。观察拒绝日志时，也要区分“来源被网络层拒绝”和“请求到达后签名或事件校验失败”，两者的修复入口不同。

常见问题

三段新增网段要不要覆盖旧的 GitHub Webhook 地址？

不建议直接覆盖。公告表达的是新增范围，静态策略应在保留原有有效条目的基础上追加；动态策略则以 Meta API 当前 hooks 数组为准。

只加了 IP 白名单，Webhook 就安全吗？

不够。还应验证 Webhook secret、使用 HTTPS、检查事件类型和 action，并用投递标识做去重；IP 白名单解决的是来源范围，不替代消息真实性和业务幂等。