关于代码所有者

您可以使用 CODEOWNERS 文件来定义负责代码库中代码的个人或团队。

谁可以使用此功能？

拥有代码库写入权限的人员可以创建或编辑 CODEOWNERS 文件并将其列为代码所有者。拥有管理员或所有者权限的人员可以要求必须先获得代码所有者的批准，然后才能合并拉取请求。

您可以在使用 GitHub Free 和 GitHub Free for organizations 的公共代码库中以及在使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有代码库中定义代码所有者。有关更多信息，请参阅“GitHub 的计划”。

本文内容

您选择的代码所有者必须对代码库具有写入权限。当代码所有者是团队时，该团队必须是可见的，并且必须具有写入权限，即使团队的所有成员已经通过组织成员身份或其他团队成员身份直接拥有写入权限也是如此。

关于代码所有者

当有人打开修改其拥有代码的拉取请求时，会自动请求代码所有者进行审查。不会自动请求代码所有者审查草稿拉取请求。有关草稿拉取请求的更多信息，请参阅“关于拉取请求”。当您将草稿拉取请求标记为已准备好进行审查时，会自动通知代码所有者。如果您将拉取请求转换为草稿，则已订阅通知的人员不会自动取消订阅。有关更多信息，请参阅“更改拉取请求的阶段”。

当拥有管理员或所有者权限的人员启用了必需的审查时，他们还可以选择要求在作者合并代码库中的拉取请求之前获得代码所有者的批准。有关更多信息，请参阅“关于受保护分支”。

如果文件有代码所有者，则您可以在打开拉取请求之前查看代码所有者是谁。在代码库中，您可以浏览到该文件并悬停在上以查看包含代码所有权详细信息的工具提示。

Screenshot showing the header for a file. The cursor is hovering over the shield icon, which displays the tooltip "Owned by USER or TEAM (from CODEOWNERS line NUMBER)."

CODEOWNERS 文件位置

要使用 CODEOWNERS 文件，请在代码库的 .github/、根目录或 docs/ 目录中创建名为 CODEOWNERS 的新文件，并在您想要添加代码所有者的分支中创建。如果 CODEOWNERS 文件存在于多个这些位置，GitHub 将按此顺序搜索它们并使用找到的第一个文件。

每个 CODEOWNERS 文件为代码库中的单个分支分配代码所有者。因此，您可以为不同的分支分配不同的代码所有者，例如，为默认分支上的代码库分配 @octo-org/codeowners-team，为 gh-pages 分支上的 GitHub Pages 站点分配 @octocat。

为了让代码所有者收到审查请求，CODEOWNERS 文件必须位于拉取请求的基础分支上。例如，如果您在代码库的 gh-pages 分支上将 @octocat 分配为 .js 文件的代码所有者，则当在头部分支和 gh-pages 之间打开包含对 .js 文件更改的拉取请求时，@octocat 将收到审查请求。

CODEOWNERS 和 fork

要触发审查请求，拉取请求将使用拉取请求基础分支中的 CODEOWNERS 版本。基础分支是如果合并拉取请求，拉取请求将修改的分支。

如果您从 fork 创建拉取请求，并且基础分支位于上游代码库中，则拉取请求将使用上游代码库中该分支的 CODEOWNERS 文件。如果基础分支是您 fork 中的分支，则拉取请求将使用您 fork 中该分支的 CODEOWNERS 文件，但这仅在代码所有者专门使用 write 访问权限添加到您的 fork 中时才会触发审查请求。

当您通过将鼠标悬停在上查看谁负责某个文件时，您将看到来自您查看的代码库中任何分支的 CODEOWNERS 文件中的信息。

CODEOWNERS 文件大小

CODEOWNERS 文件的大小必须小于 3 MB。超过此限制的 CODEOWNERS 文件将不会加载，这意味着不会显示代码所有者信息，并且不会请求相应的代码所有者审查拉取请求中的更改。

要减小 CODEOWNERS 文件的大小，请考虑使用通配符模式将多个条目合并到一个条目中。

CODEOWNERS 语法

警告

.gitignore 文件的一些语法规则不适用于 CODEOWNERS 文件

  • 使用 \ 转义以 # 开头的模式使其被视为模式而不是注释不起作用
  • 使用 ! 否定模式不起作用
  • 使用 [ ] 定义字符范围不起作用

CODEOWNERS 文件使用与 gitignore 文件中使用的规则大部分相同的模式。该模式后面跟着一个或多个使用标准 @username 或 @org/team-name 格式的 GitHub 用户名或团队名称。用户和团队必须对代码库具有明确的 write 访问权限，即使团队成员已经拥有访问权限也是如此。

如果要使用相同的模式匹配两个或多个代码所有者，则所有代码所有者必须位于同一行。如果代码所有者不在同一行，则该模式仅匹配最后提到的代码所有者。

在大多数情况下，您还可以通过已添加到其帐户的电子邮件地址引用用户，例如 [email protected]。您不能使用电子邮件地址来引用托管用户帐户。有关托管用户帐户的更多信息，请参阅 GitHub Enterprise Cloud 文档中的“关于企业托管用户”。

CODEOWNERS 路径区分大小写，因为 GitHub 使用区分大小写的文件系统。由于 CODEOWNERS 由 GitHub 评估，即使是不区分大小写的系统（例如 macOS）也必须在 CODEOWNERS 文件中使用大小写正确的路径和文件。

如果 CODEOWNERS 文件中的任何一行包含无效语法，则该行将被跳过。当您导航到代码库中的 CODEOWNERS 文件时，您可以看到任何突出显示的错误。还可以通过 API 访问代码库的 CODEOWNERS 文件中的错误列表。有关更多信息，请参阅“存储库的 REST API 端点”。

如果您指定的用户或团队不存在或访问权限不足，则不会分配代码所有者。

CODEOWNERS 文件示例

# This is a comment.
# Each line is a file pattern followed by one or more owners.

# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
*       @global-owner1 @global-owner2

# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js    @js-owner #This is an inline comment.

# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go [email protected]

# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
# explicit write access to the repository. In this example,
# the octocats team in the octo-org organization owns all .txt files.
*.txt @octo-org/octocats

# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat

# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/*  [email protected]

# In this example, @octocat owns any file in an apps directory
# anywhere in your repository.
apps/ @octocat

# In this example, @doctocat owns any file in the `/docs`
# directory in the root of your repository and any of its
# subdirectories.
/docs/ @doctocat

# In this example, any change inside the `/scripts` directory
# will require approval from @doctocat or @octocat.
/scripts/ @doctocat @octocat

# In this example, @octocat owns any file in a `/logs` directory such as
# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes
# in a `/logs` directory will require approval from @octocat.
**/logs @octocat

# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as its owners are left empty. Without an owner, changes
# to `apps/github` can be made with the approval of any user who has
# write access to the repository.
/apps/ @octocat
/apps/github

# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as this subdirectory has its own owner @doctocat
/apps/ @octocat
/apps/github @doctocat

CODEOWNERS 和分支保护

代码库所有者可以更新分支保护规则以确保更改的代码已由更改文件的拥有者审查。编辑您的分支保护规则并启用“要求来自代码所有者的审查”选项。有关更多信息，请参阅“关于受保护分支”。

注意

当需要来自代码所有者的审查时，来自任何所有者的批准都足以满足此要求。例如，假设您的 CODEOWNERS 文件包含以下行

*.js     @global-owner1 @global-owner2

这意味着对 JavaScript 文件的更改可以由 @global-owner1或@global-owner2 批准，但不需要两者都批准。

要完全保护代码库免受未经授权的更改，您还需要为 CODEOWNERS 文件本身定义所有者。最安全的方法是在代码库的 .github 目录中定义 CODEOWNERS 文件，并将代码库所有者定义为 CODEOWNERS 文件（/.github/CODEOWNERS @owner_username）或整个目录（/.github/ @owner_username）的所有者。

作为分支保护规则的替代方案，您可以创建规则集。与分支保护规则相比，规则集具有一些优势，例如状态和更好的可发现性，而无需管理员访问权限。您还可以同时应用多个规则集。有关更多信息，请参阅“关于规则集”。

进一步阅读