codeowners

codeowners

编写并维护 CODEOWNERS 文件，然后配置规则集规则，将其设为强制审核要求。

本技能涵盖一个文件及其所关联的规则。它不会配置一般性的分支规则集（/gh-bootstrap）或社区健康文件（/oss-hygiene）。

何时使用

• 用户要求添加或更新 CODEOWNERS 文件。
• 用户询问某个路径的所有者，或希望根据 git 历史记录获取所有权建议。
• 用户要求在拉取请求中强制要求所有者审核。
• 用户要求验证现有的 CODEOWNERS 文件。

流程

1. 检测现有文件和默认分支

GitHub 会按以下顺序检查三个位置的 CODEOWNERS：.github/、仓库根目录，然后是 docs/。只有找到的第一个文件会生效。

for path in .github/CODEOWNERS CODEOWNERS docs/CODEOWNERS; do
  test -f "$path" && echo "Found: $path"
done
REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
DEFAULT_BRANCH="$(gh repo view "$REPO" --json defaultBranchRef --jq '.defaultBranchRef.name')"

如果多个位置都有文件，请告知用户只有第一个匹配项（依次为 .github/、根目录、docs/）有效，并询问要保留哪个。如果都不存在，请询问要在哪个位置创建；.github/CODEOWNERS 是惯用选择，因为这样可以将仓库策略文件放在一起。

2. 收集所有权依据

提供两种方法。将结果作为建议呈现，并在编写任何规则前与用户确认——绝不自动指定所有者。

按目录结构静态分析。 列出顶层和第二层目录，作为候选所有权边界：

git ls-files | awk -F/ 'NF>1 {print $1"/"$2"/"} NF==1 {print $1}' | sort -u

按提交者分析历史记录。 对于给定路径，按提交次数排列贡献者，并列出不重复的作者：

git shortlog -sn -- <path>
git log --format=%an -- <path> | sort -u

提交次数最多的人选只是候选人，而非最终决定。将每位候选人的姓名或电子邮件地址与 GitHub 用户名或团队进行匹配，然后再写入文件——如果 CODEOWNERS 条目无法对应到有效的 GitHub 用户，或具有写入权限的团队，该条目会被 GitHub 静默忽略，而不会报错。

3. 编写规则

按照用户确认的顺序编写规则，并遵循 CODEOWNERS 语法：

• 最后匹配的模式优先。 先写通用规则，再写具体的覆盖规则。文件匹配的是最后一条匹配行，而非第一条。
• @org/team 需要写入权限。 只有明确授予团队对仓库的写入权限后，团队引用才会生效；仅加入组织并不足够。写入该行之前，请确认团队存在，然后再确认其具有写入权限（参见“防护措施”）。
• 末尾的 * 回退规则（* @org/default-owners）会匹配其他规则均未匹配的路径。将其放在最前面，以便下面更具体的规则可以覆盖它。
• 路径模式遵循 .gitignore 语法：/dir/ 锚定到仓库根目录，不带前导斜杠的 dir/ 可匹配任意位置，*.ext 按扩展名匹配。目录会递归匹配，除非进一步缩小范围。
• 注释以 # 开头；# Frontend 等分区标题可将相关规则分组，以便阅读；如果使用 #SECTION_NAME 块编写，GitHub 也会在文件审核界面中将分区显示为具名分组。

完整的语法和优先级说明请参阅 references/syntax.md，起始模板请参阅 assets/CODEOWNERS.example。

写入前，请将任何现有文件与拟议内容进行差异比较，并向用户展示差异。不要静默覆盖。

4. 验证

将文件推送到默认分支后，GitHub 可以检查其中的语法和所有权错误：

gh api "repos/$REPO/codeowners/errors"

此处返回 404 表示默认分支的三个有效位置中均未找到 CODEOWNERS 文件——请先推送，再重新检查。返回 200 且 errors 数组为空，表示文件有效。非空条目会指出行号和问题（未知用户、团队没有写入权限、模式无效）。

推送前，可在本地进行基本检查，确认规则所指向的路径确实存在于目录树中：

git ls-files -- '<path pattern from the rule>'

结果为空表示规则的模式没有匹配到任何已跟踪内容，这通常是拼写错误。

5. 使用规则集规则强制执行

CODEOWNERS 本身只会请求评审；它不会阻止合并。 要要求代码所有者批准评审，默认分支规则集的 pull_request 规则需要设置 require_code_owner_review: true：

gh api "repos/$REPO/rulesets" --jq '.[] | select(.target=="branch") | {id, name}'
gh api "repos/$REPO/rulesets/<id>" --jq '.rules[] | select(.type=="pull_request")'

向用户展示当前的 pull_request 规则参数和拟议的更改（require_code_owner_review: true），并在进行任何写入前获得明确授权：

gh api -X PUT "repos/$REPO/rulesets/<id>" --input "$TMPDIR/ruleset.json"

有关完整参数集，以及配套的 required-reviewer 规则集规则（GA 2026-02-17），请参阅 references/enforcement.md。该规则要求特定团队针对指定路径模式进行批准，且独立于 CODEOWNERS。GitHub 将此规则描述为对 CODEOWNERS 的补充，而非替代：CODEOWNERS 仍负责自动请求评审者，而 required-reviewer 规则则在规则集层级强制执行策略。将其作为一个选项提及；除非用户提出要求，否则不要启用。

6. 验证并报告

• CODEOWNERS 文件的位置和内容与用户确认的一致。
• gh api repos/$REPO/codeowners/errors 返回空的 errors 数组（如果文件尚未推送，则解释 404）。
• 已确认每个 @org/team 引用都具有写入权限。
• 规则集的 pull_request.require_code_owner_review 值与已授权的值一致（如果用户拒绝启用强制执行，则报告已跳过）。

防护措施

• 覆盖现有 CODEOWNERS 文件前，先检查差异；如果用户未确认要替换其内容，则先征求同意。
• 切勿臆造 GitHub 用户名或团队 slug。将 @org/team 添加到规则前，运行 gh api -H 'Accept: application/vnd.github.v3.repository+json' orgs/{org}/teams/{slug}/repos/$REPO。要求 .permissions.push 为 true。404 表示该团队不存在、没有访问权限，或对你的令牌不可见。在请求授予访问权限前，使用 gh api orgs/{org}/teams/{slug} 确认 slug。
• 未获得用户对相应写入的明确授权时，切勿修改规则集（require_code_owner_review 或 required-reviewer 规则）。
• 在已配置的仓库上重新运行此技能时，除非用户要求更改，否则不得进行任何操作；提议编辑前，重新读取当前文件和规则集状态。

此技能不适用于

• 一般分支规则集（合并队列、必需状态检查、PR 评审数量）——请使用 /gh-bootstrap。
• 社区健康文件（README、LICENSE、CODE_OF_CONDUCT、CONTRIBUTING、SECURITY、问题和 PR 模板）——请使用 /oss-hygiene。
• 与收集所有权证据无关的本地 git 操作。