创建存储库的规则集

可以将规则集添加到存储库，以控制用户如何与特定分支和标记交互。

谁可以使用此功能？

对存储库具有读取访问权限的任何人都可以查看存储库的规则集。 对仓库具有管理员访问权限的人员或者具有“编辑仓库规则”权限的自定义角色可以为仓库创建、编辑和删除规则集并查看规则集见解。 有关详细信息，请参阅“关于自定义存储库角色”。

规则集在具有 GitHub Free 和 GitHub Free（适用于组织）的公共存储库中可用，在具有 GitHub Pro、GitHub Team 和 GitHub Enterprise Cloud 的公共和专用存储库中可用。

本文内容

简介

可以创建规则集来控制用户如何与存储库中的选定分支和标记交互。 可以控制谁可以将提交推送到特定分支以及提交的格式必须如何设置，或者谁可以删除或重命名标记。 还可以阻止用户重命名存储库。

创建规则集时，可以允许某些用户绕过规则集中的规则。

有关规则集的详细信息，请参阅“关于规则集”。

对于订阅 GitHub Team 和 GitHub Enterprise 计划的客户，你还可以在组织中创建仓库规则集。 有关详细信息，请参阅“创建组织中存储库的规则集”。

使用 fnmatch 语法

创建规则集时，可以使用 fnmatch 语法来定义要针对的模式。

可以使用 * 通配符来匹配任何字符串。 由于 GitHub 对 File.fnmatch 语法使用 File::FNM_PATHNAME 标记，因此 * 通配符与目录分隔符 (/) 不匹配。 例如，qa/* 将匹配以 qa/ 开头并包含单个斜杠的所有分支，但不会匹配 qa/foo/bar。 可以使用 qa/**/* 在 qa 后面包含任意数量的斜杠，这将匹配 qa/foo/bar/foobar/hello-world。 还可以使用 qa**/**/* 扩展 qa 字符串，以使规则更具包容性。

有关语法选项的详细信息，请参阅 fnmatch 文档。

不支持的 fnmatch 语法

并非 fnmatch 语法中的所有表达式都受分支保护规则支持。 请注意以下约束条件：

  • 不能将反斜杠 (\) 字符用作引号，因为 GitHub 不支持在分支保护规则中使用反斜杠。
  • 可以在方括号 ([]) 中指定字符集，但当前不能用 ^ 运算符（例如 [^charset]）来补充该字符集。
  • 尽管 GitHub 支持 fnmatch 语法中的 File::FNM_PATHNAME，但不支持 File::FNM_EXTGLOB。

对提交元数据使用正则表达式

在为针对分支或标签的规则集添加元数据限制时，你可以使用正则表达式语法定义相关元数据（如提交消息或分支或标签名称）必须匹配或不能匹配的模式。

默认情况下，元数据限制不会接受正则表达式模式。 若要启用此功能，请在为规则集创建元数据限制时，选择“必须与指定正则表达式模式匹配”**** 限制。

规则集支持 RE2 语法。 有关详细信息，请参阅 Google 的语法指南。 若要验证表达式，可以使用 regex101.com 上的验证程序，并在左侧边栏中选择“Golang”风格。

默认情况下，元数据限制中的正则表达式不考虑多行文本。 例如，如果有多行提交消息，且如果消息中的第一行以 ABC 开头，则模式 ^ABC 是一个匹配项。 要匹配消息的多行，可以在表达式的开头使用 (?m)。

不支持负向先行断言（表示 ?!）。 但是，对于需要查找后面不带某个给定字符串的另一个给定字符串的情况，可以将正向先行断言（表示 ?）和“不得匹配给定正则表达式模式”要求结合使用。

注意

如果要求参与者注销提交，这可能会干扰正则表达式模式。 当某人注销时，GitHub 会向提交消息添加类似于 Signed-off-by: #AUTHOR-NAME <#AUTHOR-EMAIL> 的字符串。 有关详细信息，请参阅“管理组织的提交签核策略”。

有用的正则表达式模式

以下示例提供了有用的提交元数据模式。 若要使用这些模式，请将“要求”设置为“必须匹配给定的正则表达式模式”。

确保分支名称与 Windows 兼容

可以使用以下模式来确保分支名称仅包含数字、小写字母以及字符 - 和 _。 这可确保分支名称与默认不使用区分大小写的文件系统的操作系统兼容。

Text
\A[0-9a-z-_]$

匹配：my-branch

不匹配：myBranch

确保标记名称使用语义版本控制

可以使用以下模式来确保标记名称符合语义版本控制。 有关详细信息，请参阅 semver.org 上的文档。

Text
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

匹配：1.2.3、10.20.30、1.1.2-prerelease+meta

不匹配：1.2、1.2-SNAPSHOT

限制提交消息中的行长度

Pro Git 手册建议将提交消息的第一行限制在 50 个字符左右。

可以使用以下模式来确保提交消息中的第一行包含不超过 50 个字符。

Text
\A.{1,50}$
确保提交消息以解决方法和问题编号开头

可以使用以下模式来确保提交消息包含字词 Resolves: 或 Fixes: 且后跟类似于 #1234 的字符串。

Text
^(Resolves|Fixes): \#[0-9]+$

匹配：Fixes: #1234

不匹配：Add conditional logic to foo.bar

强制实施常规提交

可以使用以下模式来确保提交消息符合常规提交规范。 有关详细信息，请参阅 conventionalcommits.org。

Text
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)

匹配：feat: allow provided config object to extend other configs

不匹配：Add conditional logic to foo.bar

使用规则集强制实施状态

创建或编辑规则集时，可以使用强制状态来配置规则集的强制实施方式。

可以为规则集选择以下任何强制状态。

  • 活动：规则集创建后便会强制实施。****
  • 评估：不会强制执行规则集，但你将能够在“规则见解”页面上监控哪些操作会或不会违反规则。****
  • 已禁用：不会强制实施或评估规则集。****

使用“评估”模式是在不强制执行规则集的情况下测试规则集的绝佳选择。 可以使用“规则见解”页查看贡献是否违反了规则。 有关详细信息，请参阅“管理存储库的规则集”。

创建分支或标签规则集

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在左侧边栏的“代码和自动化”下，单击“规则”，然后单击“规则集” 。

    存储库“设置”页边栏的屏幕截图。 “规则”子菜单已展开，“规则集”选项以橙色轮廓突出显示。

  4. 可以创建面向分支的规则集，也可以创建面向标记的规则集。

    • 若要创建面向分支的规则集，请单击“新建分支规则集”。

    • 若要创建面向标记的规则集，请选择 ，然后单击“新建标记规则集”。

      “规则集”页的屏幕截图，其中显示了展开的“新建分支规则集”下拉菜单。 以橙色框出了“新建标记规则集”选项。

  5. 在“规则集名称”下，键入规则集的名称。

  6. （可选）若要更改默认强制实施状态，请单击 “已禁用”**** 并选择强制实施状态。 有关强制状态的详细信息，请参阅关于规则集。

为分支或标签规则集授予旁路权限

你可以授予特定角色、团队或应用绕过权限 以及批准规则集的绕过请求 的功能。 以下项符合绕过访问的条件：

  • 存储库管理员、组织所有者和企业所有者
  • 维护或写入角色，或是基于写入角色的自定义存储库角色
  • 团队
  • 部署密钥
  • GitHub Apps
  • Dependabot。 有关 Dependabot 的详细信息，请参阅“Dependabot 快速入门指南”。

  1. 若要授予规则集的绕过权限，请在“Bypass list”部分中单击 “Add bypass”****。

  2. 在显示的“添加绕过”模式对话框中，搜索要授予绕过权限的角色、团队或应用，然后从“建议”部分选择角色、团队或应用，然后单击“添加所选”****。

  3. （可选）若要向执行组件授予旁路权限，而不允许它们直接推送到存储库，请在“始终允许”右侧单击 ，然后单击“仅针对拉取请求”****。

    现在，选择的执行组件需要打开拉取请求才能对存储库进行更改，从而创建其拉取请求和审核日志更改的清晰痕迹。 然后，参与者可以选择绕过任何分支保护，以及合并该拉取请求。

选择要作为目标的分支或标签

若要定位分支或标记，在“目标分支”或“目标标记”部分，选择“添加目标”****，然后选择包含或排除分支或标记的方式。 可以使用 fnmatch 语法基于模式包含或排除分支或标记。 有关详细信息，请参阅“使用 fnmatch 语法”。

可以将多个目标条件添加到同一规则集。 例如，可以包含默认分支，包含与模式 *feature* 匹配的任何分支，然后专门排除与模式 not-a-feature 匹配的分支。

选择分支或标记保护

在“分支保护”或“标记保护”部分中，选择要包含在规则集中的规则。 选择规则时，可以输入规则的其他设置。 有关规则的详细信息，请参阅“规则集的可用规则”。

注意

如果选择“Require status checks before merging”，请在“Additional settings”部分执行以下操作：****

  • 可以输入所需的每个状态检查的名称。 若要完成添加状态检查作为要求，必须单击 。
  • 如果选择“合并前要求分支保持最新状态”，则必须定义检查才能使保护生效。

添加元数据限制

元数据限制应旨在提高存储库中提交之间的一致性。 它们不是要取代安全措施（例如要求通过拉取请求进行代码评审）。

注意

如果 Squash 合并分支，该分支上的所有提交都必须满足基础分支的任何元数据要求。

  1. 若要添加用于控制提交元数据或分支名称的规则，请在创建或编辑规则集时在“限制”部分单击“限制提交元数据”或“限制分支名称”********。

  2. 配置限制的设置，然后单击“添加”****。 可以向同一规则集添加多个限制。

  3. 若要匹配指定正则表达式模式，请在“要求”下拉列表中选择“必须与指定正则表达式模式匹配”****。

    对于大多数要求（如“必须从匹配模式开始”），输入的模式按字面解释，不支持通配符。 例如，* 字符仅表示文本 * 字符。

    对于更复杂的模式，可以选择“必须匹配给定的正则表达式模式”或“不能匹配给定的正则表达式模式”，然后使用正则表达式语法来定义匹配模式。 有关详细信息，请参阅 GitHub Enterprise Cloud 文档中的“关于适用于提交元数据的正则表达式”。

    查看存储库规则集的任何人都可以看到你提供的说明。

  4. （可选）在制定具有元数据限制的规则集之前，可以为规则集选择“评估”强制状态，以测试任何元数据限制的影响，而不会影响参与者。 有关元数据限制的详细信息，请参阅“规则集的可用规则”。

完成分支或标签规则集和后续步骤

单击“创建****”即可完成规则集的创建。 如果规则集的强制执行状态设置为“活动”，规则集会立即生效。

可以查看规则集的见解，了解规则如何影响参与者。 如果强制执行状态设置为“评估”，则可以看到规则集处于活动状态时已经传递或失败的操作。 有关规则集见解的详细信息，请参阅“管理存储库的规则集”。