GitHub 怎么用 CODEOWNERS 自动请求评审

GitHub 的 CODEOWNERS 文件可以按目录、文件类型或具体路径分配评审责任人。配置完成后，Pull Request 修改了对应文件，GitHub 就会自动请求匹配的个人或团队评审。要让它稳定生效，关键不只是写几行路径：CODEOWNERS 必须位于 PR 的 base 分支，所有者要有仓库写权限，草稿 PR 也不会立即触发自动请求。

官方地址：https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

先确认 CODEOWNERS 的位置和生效条件

GitHub 会依次查找仓库的 .github/、根目录和 docs/ 下的 CODEOWNERS，找到第一个就停止。一个仓库在不同分支可以有不同文件，因此不要只在开发分支修改后就期待默认分支上的 PR 立刻改变评审人。来自 fork 的 PR 也以目标仓库 base 分支中的 CODEOWNERS 为准。

个人或团队必须对仓库拥有 write 权限；团队还需要对组织可见。文件超过 3 MB、路径大小写错误、团队名不存在，都会让部分规则无法分配负责人。配置前先确定要保护的 base 分支和目录边界。

步骤一：创建按目录分配责任人的规则文件

在默认分支的 .github/CODEOWNERS 创建文件。下面的写法把全仓库、前端、API 和规则文件本身分开管理：

# 默认规则：没有更具体匹配时由平台组评审
* @acme/platform

# 前端目录由前端组负责
/web/ @acme/frontend

# API 目录可由后端组或架构师共同评审
/api/ @acme/backend @acme/architecture

# CODEOWNERS 自己也要有人维护
/.github/CODEOWNERS @acme/platform

同一条模式的多个负责人必须写在同一行，否则只有最后出现的负责人会被该模式采用。目录规则前的斜杠表示从仓库根目录匹配；模式越具体、越靠后，通常越能覆盖前面的通用规则。CODEOWNERS 支持很多 gitignore 风格的模式，但不支持用 ! 做否定匹配，也不能依赖字符范围语法。

步骤二：检查最后匹配规则和分支边界

打开仓库中的 CODEOWNERS 文件，先看 GitHub 标出的语法错误，再逐条检查三件事：路径是否区分大小写、负责人是否仍有 write 权限、文件是否已经提交到目标 base 分支。比如 /Web/ 和实际目录 /web/ 不会被当成同一路径。

可以从一个目录范围较小的 PR 开始验证。修改 web/ 下的文件时，预期出现 @acme/frontend；如果同时命中全局规则和目录规则，应以更靠后的具体规则为准。没有负责人或语法无效时，不要把“没有自动请求”误判成 GitHub 通知延迟。

步骤三：打开代码所有者评审门禁

仅有 CODEOWNERS 时，GitHub 会自动发起 review request，但不一定阻止合并。进入仓库设置中的分支保护规则，或创建对应 ruleset，启用 Require review from Code Owners。这样修改了受保护目录的 PR，至少需要一名匹配的代码所有者批准后才能合并。

把 /.github/CODEOWNERS 指向平台负责人很重要，否则修改规则文件的人可能绕过自己定义的责任边界。启用门禁后，先在测试分支创建一个小 PR，确认 Reviewers 区域出现正确团队，再把规则推广到默认分支。

步骤四：用非草稿 Pull Request 验收结果

1. 从功能分支创建一个修改目标目录文件的 Pull Request，并确认 base 分支就是放置 CODEOWNERS 的分支。
2. 如果 PR 仍是 Draft，先点击 Ready for review；GitHub 不会在草稿阶段自动请求代码所有者。
3. 检查 Reviewers 区域、文件归属提示和分支保护检查项，确认团队成员能够收到通知。

建议把“路径、预期负责人、实际负责人、是否需要批准”记成一张小表，至少覆盖一个全局规则、一个目录规则和 CODEOWNERS 自身。这样能同时发现规则匹配错误和门禁未启用的问题。

常见问题

为什么 CODEOWNERS 写了但没有自动请求？

优先检查文件是否在 PR 的 base 分支、PR 是否仍是草稿、负责人是否有 write 权限，以及路径大小写和团队可见性。

同一目录需要两个人都批准吗？

同一行写多个负责人代表他们都可作为匹配所有者；启用代码所有者必需批准时，通常任意一名匹配所有者批准即可满足该项。

能不能用 CODEOWNERS 排除某个子目录？

不要依赖 ! 否定模式。更稳妥的方式是把例外子目录写成后置的空负责人或明确负责人规则，并在测试 PR 中验证实际匹配结果。

CODEOWNERS 的核心是“路径匹配 + 有效权限 + 正确 base 分支 + 合并门禁”四件事同时成立。先用小范围 PR 验收，再扩大目录规则，通常比一次性覆盖整个仓库更容易定位责任人错派问题。