Skip to main content

关于代码所有者

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

谁可以使用此功能?

People with write permissions for the repository can create or edit the CODEOWNERS file and be listed as code owners. People with admin or owner permissions can require that pull requests have to be approved by code owners before they can be merged.

可以在公共存储库中使用 GitHub Free 和 GitHub Free 为组织定义代码所有者,也可以在公共和专用存储库中使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 定义代码所有者。 有关详细信息,请参阅“GitHub 的计划”。

你选择作为代码所有者的人员必须具有仓库的写入权限。 当代码所有者是团队时,该团队必须可见且必须拥有写入权限,即使团队的所有成员都已经直接通过组织成员资格或通过另一个团队成员资格直接拥有写入权限。

关于代码所有者

当有人打开修改代码的拉取请求时,将自动请求代码所有者进行审查。 不会自动请求代码所有者审查拉取请求草稿。 有关草稿拉取请求的详细信息,请参阅“关于拉取请求”。 不会自动请求代码所有者审查拉取请求草稿。 如果将拉取请求转换为草稿,则已订阅通知的用户不会自动取消订阅。 有关详细信息,请参阅“更改拉取请求的阶段”。

当具有管理员或所有者权限的人员启用必需审查时,他们也可选择性要求代码所有者批准后,作者才可合并仓库中的拉取请求。 有关详细信息,请参阅“关于受保护分支”。

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

显示文件标头的屏幕截图。 光标悬停在盾牌图标上,该图标显示工具提示“由用户或团队拥有(来自 CODEOWNERS 行号)”。

CODEOWNERS 文件位置

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

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

为使代码所有者接收审查请求,CODEOWNERS 文件必须在拉取请求的基本分支上。 例如,如果将 @octocat 分配为存储库 gh-pages 分支上 .js 文件的代码所有者,则在头部分支与 gh-pages 之间打开更改 .js 文件的拉取请求时,@octocat 将会收到审查请求 。

CODEOWNERS 和分支

若要触发审查请求,拉取请求将使用拉取请求基本分支的 CODEOWNERS 版本。 基本分支是合并拉取请求时拉取请求将会修改的分支。

如果从分支创建拉取请求,而基本分支位于上游存储库中,则拉取请求将使用上游存储库中该分支的 CODEOWNERS 文件。 如果基本分支是分支中的分支,则拉取请求将使用分支中该分支的 CODEOWNERS 文件,但只有当代码所有者专门添加到具有 write 访问权限的分支时,才会触发审查请求。

当你将鼠标悬停在 上查看文件负责人时,你将从 CODEOWNERS 文件中看到你正在查看的存储库中任何分支的信息。

CODEOWNERS 文件大小

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

要减小 CODEOWNERS 文件的大小,请考虑使用通配符模式将多个条目合并为单个条目。

CODEOWNERS 语法

警告:gitignore 文件有一些语法规则在 CODEOWNERS 文件中不起作用:

  • 使用 \ 对以 # 开头的模式进行转义,就可将其视为模式而不是注释
  • 使用 ! 否定模式
  • 使用 [ ] 定义字符范围

CODEOWNERS 文件使用遵循 gitignore 文件中所用的大多数相同规则的模式。 模式后接一个或多个使用标准 @username@org/team-name 格式的 GitHub 用户名或团队名称。 用户和团队必须具有对存储库的显式 write 访问权限,即使团队成员已具有访问权限也是如此。

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

在大多数情况下,你还可通过已添加到用户在 GitHub.com 上帐户的电子邮件地址来引用用户,例如 user@example.com。 不能使用电子邮件地址来引用托管用户帐户。 有关 托管用户帐户 的详细信息,请参阅 GitHub Enterprise Cloud 文档中的“关于 Enterprise Managed Users."

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

如果 CODEOWNERS 文件中的任何行包含无效语法,将跳过该行。 导航到 GitHub.com 存储库中的 CODEOWNERS 文件时,可以看到突出显示的所有错误。 存储库的 CODEOWNERS 文件中的错误列表也可以通过 API 访问。 有关详细信息,请参阅 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 docs@example.com

# 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/*  docs@example.com

# 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.
/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 文件本身定义所有者。 最安全的方法是在存储库的 .github 目录中定义 CODEOWNERS 文件,同时将存储库所有者定义为 CODEOWNERS 文件 (/.github/CODEOWNERS @owner_username) 或整个目录 (/.github/ @owner_username) 的所有者。

可以创建规则集作为分支保护规则或标签保护规则的替代方法。 规则集相比分支和标签保护规则拥有状态等几项优势,并且可发现性更好,无需管理员访问权限。 还可以同时应用多个规则集。 有关详细信息,请参阅“关于规则集”。

延伸阅读