Help us learn about your current experience with the documentation. Take the survey.

高级 `CODEOWNERS` 配置

CODEOWNERS 文件帮助你定义谁负责特定的文件和目录。你可以使用模式匹配、区块和继承规则来为合并请求分配审查者，并要求他们在合并前获得批准。

模式匹配

GitLab 使用 File::fnmatch 并设置了 File::FNM_DOTMATCH 和 File::FNM_PATHNAME 标志来进行模式匹配：

仓库结构被视为独立的文件系统。
模式遵循 shell 文件名 globbing 规则的子集，不是正则表达式。
File::FNM_DOTMATCH 标志允许 * 匹配点文件，如 .gitignore。
File::FNM_PATHNAME 标志防止 * 匹配 / 路径分隔符。
** 递归匹配目录。例如，**/*.rb 匹配 config/database.rb 和 app/controllers/users/stars_controller.rb。

默认代码所有者和可选区块

要将默认所有者的语法与可选区块和必需批准结合使用，请将默认所有者放在末尾：

[Documentation][2] @docs-team
docs/
README.md

^[Database] @database-team
model/db/
config/db/database-setup.md @docs-team

常规条目和区块

如果你在区块外为路径设置默认代码所有者，他们的批准总是必需的。这样的条目不会被区块覆盖。没有区块的条目被视为另一个未命名区块：

# 所有文件都需要
* @general-approvers

[Documentation] @docs-team
docs/
README.md
*.txt

[Database] @database-team
model/db/
config/db/database-setup.md @docs-team

在此示例中：

@general-approvers 拥有所有项目，没有覆盖。
@docs-team 拥有 Documentation 区块中的所有项目。
@database-team 拥有 Database 区块中的所有项目，除了 config/db/database-setup.md，它有一个覆盖规则将其分配给 @docs-team。
修改 model/db/CHANGELOG.txt 的合并请求需要三个批准：分别来自 @general-approvers、@docs-team 和 @database-team 组。

将此行为与仅使用区块的默认所有者时进行比较，此时区块中的特定条目会覆盖区块默认值。

重复名称的区块

如果多个区块具有相同的名称，它们会被合并。此外，区块标题不区分大小写。例如：

[Documentation]
ee/docs/    @docs
docs/       @docs

[Database]
README.md  @database
model/db/   @database

[DOCUMENTATION]
README.md  @docs

此代码在 Documentation 区块标题下产生三个条目，在 Database 下产生两个条目。 Documentation 和 DOCUMENTATION 区块下定义的条目会被合并，使用第一个区块的大小写。

为特定文件或目录定义代码所有者

当文件或目录匹配 CODEOWNERS 文件中的多个条目时，使用最后匹配该文件或目录的用户。这使你能够以合理的方式排列条目，为更具体定义的文件或目录定义更具体的所有者。

例如，在以下 CODEOWNERS 文件中：

# 这行会匹配 terms.md 文件
*.md @doc-team

# 这行也会匹配 terms.md 文件
terms.md @legal-team

terms.md 的代码所有者将是 @legal-team。

要求代码所有者多次批准

你可以在合并请求的批准区域要求代码所有者区块多次批准。在区块名称后附加带括号的数字 n，例如 [2] 或 [3]。这要求该区块的代码所有者提供 n 次批准。 n 的有效条目是整数 ≥ 1。[1] 是可选的，因为它是默认值。n 的无效值被视为 1。

Issue 384881 提议更改此设置的行为。不要故意设置无效值。它们可能会在未来变得有效并导致意外行为。

要要求代码所有者多次批准：

在左侧边栏，选择 Search or go to 并找到你的项目。
选择 Settings > Repository。
展开 Protected branches。
在默认分支旁边，打开 Code owner approval 下的切换开关。
编辑 CODEOWNERS 文件以添加多次批准的规则。

例如，要求 [Documentation] 区块两次批准：

[Documentation][2]
*.md @tech-writer-team

[Ruby]
*.rb @dev-team

批准区域中的 Documentation 代码所有者区块显示需要两次批准：

组继承和资格

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Diagram of group inheritance
    accDescr: If a subgroup owns a project, the parent group inherits ownership.
    A[Parent group X] -->|owns| B[Project A]
    A -->|contains| C[Subgroup Y]
    C -->|owns| D[Project B]
    A-. inherits ownership .-> D

在此示例中：

父组 X (group-x) 拥有项目 A。
父组 X 还包含一个子组，子组 Y (group-x/subgroup-y)。
子组 Y 拥有项目 B。

有资格的代码所有者是：

项目 A：仅组 X 的成员，因为项目 A 不属于子组 Y。
项目 B：组 X 和子组 Y 的成员。

邀请子组到父组

将子组 Y 邀请到项目 A 的父组不受支持。要将子组 Y 设置为代码所有者，直接邀请该组到项目本身。

为了要求批准，作为代码所有者的组必须在项目中具有直接成员资格（非继承成员资格）。仅对继承成员资格的组，批准可以是可选的。代码所有者组中的成员也必须是直接成员，不能从任何父组继承成员资格。

邀请子组到父组中的项目

你可以邀请子组 Y 到项目 A，以便他们的成员也成为有资格的代码所有者。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Diagram of subgroup inheritance
    accDescr: Inviting a subgroup directly to a project affects whether their approvals can be made required.
    A[Parent group X] -->|owns| B[Project A]
    A -->|also contains| C[Subgroup Y]
    C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| E[Members of Subgroup Y<br/>can submit Approvals]
    D{Invite Subgroup Y<br/>to Project A?} -.->|no| F[Members of Subgroup Y<br />cannot submit Approvals]
    E -.->|Add Subgroup Y<br/> as Code Owner to Project A| I[Approvals can be<br/>required] -.-> B
    F -.-> |Add Subgroup Y<br/> as Code Owners to Project A| J[Approvals can only<br/>be optional] -.-> B

如果你不邀请子组 Y 到项目 A，但让他们成为代码所有者，他们对合并请求的批准将变为可选。

错误处理

带空格的条目

使用反斜杠转义路径中的空格：

path\ with\ spaces/*.md @owner

如果不转义，GitLab 会将 folder with spaces/*.md @group 解析为：path: "folder", owners: " with spaces/*.md @group"。

无法解析的区块

如果区块标题无法解析，该区块会：

被解析为条目。
添加到前一个区块。
如果没有前一个区块，该区块会被添加到默认区块。

在默认区块之后

* @group

[Section name
docs/ @docs_group

GitLab 将标题 [Section name 识别为条目。默认区块包含 3 条规则：

默认区块
- * 由 @group 拥有
- [Section 由 name 拥有
- docs/ 由 @docs_group 拥有

在命名区块之后

[Docs]
docs/**/* @group

[Section name
docs/ @docs_group

GitLab 将标题 [Section name 识别为条目。[Docs] 区块包含 3 条规则：

docs/**/* 由 @group 拥有
[Section 由 name 拥有
docs/ 由 @docs_group 拥有

格式错误的代码所有者

每个条目必须包含一个或多个所有者。格式错误的代码所有者无效且被忽略：

/path/* @group user_without_at_symbol @user_with_at_symbol

此条目由 @group 和 @user_with_at_symbol 拥有。

无法访问或不正确的代码所有者

GitLab 会忽略无法访问或不正确的代码所有者。例如：

* @group @grou @username @i_left @i_dont_exist [email protected] [email protected]

如果只有 @group、@username 和 [email protected] 可访问，GitLab 会忽略其他。

零个代码所有者

如果条目包含没有所有者，或者存在零个可访问的代码所有者，该条目无效。因为这个规则永远无法满足，GitLab 在合并请求中自动批准它。

当受保护分支启用了 Require code owner approval 时，零个所有者的规则仍然有效。

最少批准次数

当定义区块的批准次数时，最少批准次数是 1。将批准次数设置为 0 会导致 GitLab 要求一次批准。

高级 CODEOWNERS 配置