GitHub 分支保护规则自动迁移到 Rulesets 怎么验收：组织级权限与回滚清单

GitHub 最近直接在仓库设置里上线了分支保护规则一键转换为 Rulesets 的入口。真正容易踩坑的不是点击 Convert to ruleset，而是转换后新旧策略可能同时生效：旧规则没清掉，新的 Active 状态 Ruleset 也在运行，某个没注意到的分支模式或者遗漏的绕过角色，很可能让合并校验突然变严，甚至把日常用的发布机器人直接拦在仓库门外。

整套验收流程的核心就是先对齐旧规则基线，用观察模式跑通实测流程，确认所有校验点完全等价后再移除原有分支保护规则，全程留好快照和回滚方案，不会影响线上仓库的正常合并。

这次 GitHub 改动，实际调整的是哪一层治理逻辑

GitHub 官方更新日志里的变化点很明确：在仓库 Settings → Branches 中找到旧的 Branch protection rule，点击 Convert to ruleset，系统就会把原有配置里的必需审查、状态检查和推送限制自动映射到一个或多个 Rulesets 里。Rulesets 的好处是可以通过分支通配模式覆盖更多目标，也能在仓库、组织或企业层级统一批量管理。

但它不是简单把旧开关复制一份然后自动替换。Rulesets 支持多条规则同时作用于同一分支，生效规则会自动聚合，出现冲突时更严格的要求会被保留。迁移验收的核心其实是确认新策略完全对齐旧策略的管控意图，而不是看页面上有没有显示绿色的 Active 标识。

开始转换前，先把旧规则整理成一张基线表

建议先给每条旧规则留一份基线快照，尤其是生产仓库的 main、release/* 和热修复分支。下面这张表不需要写得很复杂，但每一项配置都要能在迁移后的新规则里找到对应位置。

这里最容易漏的是模式边界校验。比如旧规则写的是 release/*，它不一定等价于“所有多级路径下的 release 分支”。不要凭名称猜结果，直接拿仓库里现有的分支名做命中测试，把预期结果同步写到变更记录里。

按官方页面路径转换，先观察新规则行为再启用

在仓库主页依次打开 Settings、Code and automation → Branches，找到目标 Branch protection rule 后选择 Convert to ruleset。转换向导可能生成多个 Rulesets，需要分别命名并仔细阅读 New behavior 区域的提示内容。

1. 先选一条影响面最小、但完全能代表生产门禁逻辑的规则做试点。
2. 逐个确认生成的 Ruleset 名称、分支目标和所有必需检查项。
3. 首次迁移选择“观察模式”，让规则仅记录“如果启用会拦截什么操作”，暂时不实际阻断合并。
4. 保留原分支保护规则，提交测试用的 Pull Request，分别用普通贡献者、审查者和发布机器人账号走一遍流程验证。

如果当前账号或付费计划不具备编辑仓库规则的权限，转换入口可能不会显示。官方文档把创建、编辑和删除 Rulesets 的权限归到仓库管理员，或是拥有 edit repository rules 权限的自定义角色，先确认权限范围比反复刷新设置页更省时间。

用一条 Pull Request 验收四个核心行为

验收环节不要只盯着 Ruleset 详情页看配置。至少要完成四个实际操作，把结果同步贴进变更记录：

• 用普通贡献者账号向目标分支发起 Pull Request，确认必需审查人数和状态检查要求和之前完全一致。
• 手动让一个状态检查失败，确认合并按钮仍被门禁拦住，并且检查项名称没有因为转换出现重复。
• 用维护团队账号或者发布 App 走一遍之前允许的例外路径，确认 bypass actor 只覆盖预期的动作。
• 在一个不应该受保护的分支上推送代码，确认新 Ruleset 的匹配模式没有误伤日常开发分支。

如果旧规则还没有删除，页面上看到“两套检查同时出现”不一定是故障，属于规则叠加的正常结果。这时要把旧规则和新 Ruleset 分开逐条记录，判断每一项校验来自哪一层，不要把重复门禁误判成新规则生成错误。

conversation resolution 是迁移里的特殊边界点

旧分支保护里的“要求解决所有对话”配置，不会在转换时自动生成同名开关。GitHub 文档明确说明，这项设置原本是分支保护里的独立能力；在 Rulesets 体系里它属于 Pull Request 规则的一部分，只有完整启用 Pull Request 规则后才有对应语义。

所以基线表里如果有这一项，验收时要单独加一个检查步骤：在 Pull Request 里留下未解决的评论，观察合并条件是否符合原仓库的约定。不要确认完审查人数和状态检查都通过，就直接判定整条策略是等价的。

什么时候可以删除旧分支保护规则

转换向导支持迁移后一键删除旧规则，但生产环境建议把删除动作拆成独立的变更环节。先让 Ruleset 在观察模式下跑完一轮真实的团队协作流程，确认目标分支、必需检查、绕过角色和对话解决要求都通过回归验证。

回到 Branches 页面，如果 GitHub 判定新 Ruleset 已经完整覆盖旧规则，旧规则旁边会出现“可安全删除”的提示。这时仍然建议保留一份旧规则的快照和删除前后的审计记录。删除后如果出现异常，回滚路径是恢复原分支保护规则，或是把 Ruleset 暂时改为 Disabled 状态，不要现场重新手动回忆一遍之前的审查人数和状态检查名称。

常见问题

Ruleset 创建成功后，为什么合并校验反而更严格了？

最常见的原因是旧分支保护规则仍在生效，新 Ruleset 又以 Active 状态叠加运行。先分别查看两层规则的配置，再决定是保留旧规则、调整新规则，还是确认完整覆盖后删除旧规则。

首次迁移一定要用观察模式吗？

不是硬性要求，但首次迁移更适合先用观察模式记录实际 Pull Request 的运行行为。对迁移流程已经很成熟、基线和回归验证都做得很充分的仓库，可以直接启用 Active 模式。

Rulesets 能不能同时覆盖多个仓库？

Rulesets 可以按照产品线和管理层级，在组织或企业范围内批量管控多个仓库，但当前介绍的转换入口是针对单个仓库的单条分支保护规则。批量治理前要再核对组织级权限、目标仓库范围和规则叠加关系。

转换后找不到原来的“解决对话”要求怎么办？

检查生成的 Pull Request 规则是否启用了对应能力。它不会像必需审查或状态检查那样，在所有场景下都自动一比一映射，必须通过带未解决评论的 Pull Request 做实测确认。

这次迁移真正的完成标志，是新旧策略的行为边界都被一次 Pull Request 回归验证过：该拦截的场景仍然会被拦截，该放行的例外权限不会扩大，观察记录和基线表能互相匹配，最后再执行删除旧规则的操作。