规则集的可用规则

了解可添加到规则集用于保护存储库中特定分支和标记的规则。

谁可以使用此功能？

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

规则集在具有 GitHub Free 和 GitHub Free（适用于组织）的公共存储库中可用，在具有 GitHub Pro、GitHub Team 和 GitHub Enterprise Cloud 的公共和专用存储库中可用。 有关详细信息，请参阅 GitHub的计划。

推送规则集适用于内部存储库和专用存储库中的 GitHub Enterprise Cloud 计划、已启用推送规则集的存储库分支，以及企业中的组织。

在本文中

可以创建分支或标签规则集来控制用户如何与存储库中的选定分支和标签交互。 还可以创建推送规则集来阻止对专用或内部存储库的推送，以及对此存储库整个分支网络的推送。

创建规则集时，可以允许某些用户绕过规则集中的规则。 这可以是具有特定角色的用户、特定团队或 GitHub Apps。

对于推送规则集，旁路权限会应用于存储库和存储库的整个分支网络。 这意味着，在此存储库的整个分支网络中，唯一可以绕过此规则集的用户是在根存储库中可以绕过此规则集的用户。

有关创建规则集和旁路权限的详细信息，请参阅 创建组织中存储库的规则集 和 创建存储库的规则集。

限制创建

如果选中，则只有具有绕过权限的用户才能创建名称与指定模式匹配的分支或标记。

限制更新

如果选中，则只有具有绕过权限的用户才能推送到名称与指定模式匹配的分支或标记。

限制删除

如果选中，则只有具有绕过权限的用户才能删除名称与指定模式匹配的分支或标记。 默认情况下，此规则处于选中状态。

需要线性历史记录

强制实施线性提交历史记录可阻止协作者将合并提交推送到目标分支或标记。 这意味着合并到分支或标记的任何拉取请求都必须使用 squash 合并或变基合并。 严格的线性提交历史记录可以帮助团队更轻松地恢复更改。 有关合并方法的详细信息，请参阅 关于拉取请求合并。

在需要线性提交历史记录之前，存储库必须允许压缩合并或变基合并。 有关详细信息，请参阅“配置拉取请求合并”。

需要合并队列

注意

  • 此规则不适用于在组织级别创建的规则集。 有关在存储库级别创建规则集的详细信息，请参阅 创建存储库的规则集。

可以要求必须在存储库级别使用合并队列执行合并。 有关合并队列的详细信息，请参阅“将拉取请求与合并队列合并”。

其他设置

可以为合并队列规则配置各种设置。

  •         **合并方法：** 合并拉取请求中的更改时使用的方法。

  •         **生成并发：** 限制请求检查和工作流同时运行的排队拉取请求的数量。
    • 此设置控制合并队列何时调度 merge_group.checks_requested webhook 事件，该事件会触发配置为在 merge_group 上运行的 GitHub Actions 工作流。 有关详细信息，请参阅“Webhook 事件和有效负载”。
    • 例如，如果队列中添加了 5 个拉取请求，并且生成并发设置为 3，则合并队列将为前 3 个拉取请求分派 checks_requested 事件。 当收到这些拉取请求之一的结果时，合并队列将为第四个拉取请求调度事件，依此类推。
  •         **最小/最大组大小：** 将合并到一个组中的拉取请求的数量。

  •         **满足最小组大小的等待时间（分钟）：** 将第一个拉取请求添加到队列后，合并队列将等待的时间，以满足最小组大小。 这段时间后，最小组大小将被忽略，较小的组将被合并。

  •         **要求所有队列条目通过所需的检查：**
    • 启用此设置后，合并组中的每个项目都必须通过所有必需的检查。
    • 禁用此设置时，只有合并组头部的提交（即包含组中所有拉取请求的更改的提交）必须通过合并所需的检查。
  •         **状态检查超时（分钟）：** 报告结论所需的状态检查的最长时间。 经过这么长时间后，未报告结论的检查将被视为失败

在合并前要求部署成功

注意

此规则不适用于在组织级别创建的规则集。

在合并分支之前，可以要求将更改成功部署到特定环境。 例如，可以使用此规则确保在更改合并到默认分支之前成功部署到过渡环境。

要求签名提交

如果你在分支上启用所需的提交签名，参与者和机器人只能将已签名和验证的提交推送到分支。 有关详细信息，请参阅“关于提交签名验证”。

使用规则集创建分支时，分支保护规则和规则集的行为有所不同：规则集仅可用于检查无法从其他分支访问的提交；若使用分支保护规则，除非限制创建匹配分支的推送，否则我们不会验证签名提交。 通过这两种方法，即使可以从其他分支访问提交，我们仍会在你更新分支时检查指定范围内的所有提交。

通过这两种方法，我们使用 verified_signature? 确认提交是否具有有效签名。 如果没有有效签名，系统则不接受更新。

注意

  • 如果在帐户设置中启用了警戒模式，这表明提交总是会签名，在需要签名提交的分支上将允许提交 GitHub 识别为“部分验证”的任何提交。 有关警戒模式的详细信息，请参阅 显示所有提交的验证状态。
  • 如果协作者将未签名的提交推送到要求提交签名的分支，则协作者需要变基提交以包含验证的签名，然后将重写的提交强制推送到分支。

如果提交已进行签名和验证，则始终可以将本地提交推送到分支。 还可以使用拉取请求将已签名和已验证的提交合并到分支中。 但除非你是拉取请求的作者，否则不能将拉取请求压缩并合并到 GitHub 上的分支。 你可以在本地压缩和合并拉取请求。 有关详细信息，请参阅“本地检查拉取请求”。

有关合并方法的详细信息，请参阅 关于GitHub上的合并方法。

在合并前需要拉取请求

可以要求对目标分支的所有更改都要与拉取请求相关联。 拉取请求不一定要得到批准，但必须开启。

其他设置

注意

如果选择“推送新提交时关闭旧拉取请求审批”和/或“需要审批最近的可评审推送”，则手动为拉取请求创建合并提交并将其直接推送到受保护分支的操作将失败，除非合并内容与 GitHub 为拉取请求生成的合并完全匹配。

此外，使用这些设置，如果合并基在提交评审后引入新更改，审批评审将因过时而被关闭。 合并基础是主题分支和基础分支之间的最后一个共同上级的提交。 如果合并基发生更改，则拉取请求在再次审批工作之前无法合并。

仓库管理员或具有“编辑仓库规则”权限的自定义角色可以要求所有拉取请求在有人将拉取请求合并到受保护分支之前接收特定数量的审批评审。 您可以要求仓库中具有写入权限的人或指定代码所有者批准审查。

如果启用必需的审查，则协作者只能通过由所需数量的具有写入权限的审查者批准的拉取请求向分支推送更改。

如果某人在审查中选择“请求更改”**** 选项，则拉取请求必须经此人批准后才可合并。 如果申请更改拉取请求的审查者没有空，则具有存储库写入权限的任何人都可忽略阻止审查。

即使在所有必需的审查者已经批准拉取请求之后，如果还有其他打开的拉取请求有头部分支指向同一待处理或拒绝审查的评论，协作者也不能合并拉请求。 具有写入权限的人必须先批准或取消对其他拉取请求的阻止审查。

（可选）可以选择在推送影响拉取请求差异的提交时关闭过时的拉取请求审批。 GitHub 记录拉取请求获得批准时的差异状态。 此状态表示审阅者批准的一组更改。 如果差异从此状态发生变化（例如，因为参与者将新更改推送到拉取请求分支或单击“更新分支”****，或者因为有相关拉取请求合并到目标分支），则审批评审会因过时而被关闭，并且在有人再次批准该工作之前无法合并拉取请求。 有关目标分支的信息，请参阅 关于拉取请求。

（可选）你可以选择要求代码所有者进行审查。 如果这样做，则任何修改内容的拉取请求都必须得到代码所有者的批准，才能合并到受保护分支。 请注意，如果代码具有多个所有者，则任何代码所有者的批准均足以满足此要求。__ 有关详细信息，请参阅“关于代码所有者”。

（可选）在合并拉取请求之前，可以需要除最后一个人以外的其他人的批准才能推送到分支。 这意味着至少有一位获得授权的其他审阅者已批准了任何更改。 例如，“最后一位审阅者”可以检查最新的一组更改是否包含来自其他评审的反馈，并且未添加新的、未经评审的内容。

对于需要多次评审的复杂拉取请求，要求最后一位推送者以外的其他人的批准是一种折中操作，这样无需关闭所有过时的评审：使用此选项时，“过时”的评审不会被关闭，并且只要进行最新更改的人以外的其他人批准了拉取请求，该拉取请求就会保持批准状态。 已审查过拉取请求的用户可以在最近一次推送后重新批准，以满足此要求。 如果担心拉取请求被“劫持”（将未经批准的内容添加到已批准的拉取请求中），则更安全的做法是关闭过时的评论。

或者，可以要求必须解决所有对拉取请求的注释才能将其合并到受保护的分支。 这确保所有评论在合并前都得到解决或确认。

（可选）可要求合并、squash 或变基等合并类型。 这意味着目标分支只能根据允许的类型进行合并。 此外，如果存储库禁用了一种合并方法，而规则集要求使用另一种方法，合并将被阻止。 请参阅“关于GitHub上的合并方法”。

需要的审查者

（可选）当拉取请求更改某些文件或目录时，你可以要求特定团队审阅或批准。 最多可以指定 15 个不同的团队，并且对于每个团队，可能需要团队成员的一定数量的批准。

通过审阅者下拉列表，您可以选择在定义规则的有效范围内的任何团队。

  •         **组织范围规则**：团队必须属于组织。

  •         **存储库级规则**：团队必须属于拥有存储库的组织。

此规则在用户拥有的存储库上不可用，因为它们不包含团队。

所需的审批可以从 0（零）设置为 10。 要求零审批意味着将添加团队以提高可见性，但团队不需要批准请求。

对于每个团队，可以指定文件模式列表，用于确定设置适用的文件。 此文件列表的格式与标准 .gitignore 文件相同：

  • 从感叹号（!）开始的模式是否定。 这将导致与早期模式匹配的路径 不需要 审批。
  • 模式按顺序进行匹配，因此否定模式可以取消与先前规则匹配的文件的匹配。

要求合并前必须通过状态检查

必需的状态检查确保了在协作者可以对规则集针对的分支或标记进行更改前，所有必需的 CI 测试都已通过。 必需的状态检查可以是检查或状态。 有关详细信息，请参阅“关于状态检查”。

可以使用提交状态 API 让外部服务能够将提交标记为适当的状态。 有关详细信息，请参阅“提交状态的 REST API 端点”。

启用必需的状态检查后，必须通过所有必需的状态检查，协作者才能将更改合并到分支或标记。 （可选）如果你希望允许创建分支而不考虑状态检查结果如何，则可以选择“创建时不需要状态检查”。

任何对存储库具有写入权限的人员或集成都可以在存储库中设置任何状态检查的状态，但在某些情况下，你可能只想接受来自特定 GitHub App 的状态检查。 添加必需的状态检查规则时，可以选择一个应用作为预期状态更新源。 应用必须使用 statuses:write 权限安装到存储库中，必须在最近提交过检查运行，并且必须与规则集中一个预先存在的必需的状态检查相关联。 如果状态由任何其他人员或集成设置，则无法合并。 如果选择“任何来源”，你仍然可以手动验证合并框中列出的每个状态的作者。

要排查在规则集中配置状态检查的问题，请参阅“排查规则”。

注意

对于组织级别的状态检查，必须通过 statuses:write 权限安装应用。 在组织级别配置规则集时，仅显示具有此权限的应用。

可以将必需的状态检查视为“宽松”或“严格”。 你选择的必需状态检查类型确定合并之前是否需要使用基础分支将你的分支保持最新状态。

必需状态检查的类型设置合并要求注意事项
          **严格** | 选中****“合并前要求分支保持最新状态”复选框。 | 在合并之前，**必须**利用基础分支使主题分支保持最新状态。 | 这是必需状态检查的默认行为。 可能需要更多构建，因为在其他协作者更新目标分支后，你需要使头部分支保持最新状态。|

| 宽松 | 未选中“合并前要求分支保持最新状态”**** 复选框。 | 在合并之前，不必利用基础分支使分支保持最新状态。 | 你将需要更少的构建，因为在其他协作者合并拉取请求后，你不需要使头部分支保持最新状态。 如果存在与基础分支不兼容的变更，则在合并分支后，状态检查可能会失败。 | | 已禁用 | 未选中“合并前要求通过状态检查”**** 复选框。 | 分支没有合并限制。 | 如果未启用必需状态检查，协作者可以随时合并分支，无论它是否使用基础分支保持最新状态。 这增加了不兼容变更的可能性。

有关状态检查故障排除信息，请参阅“必需状态检查故障排除”。

阻止强制推送

可以阻止用户强制推送到目标分支或标记。 默认情况下，此规则处于启用状态。

如果有人强制推送到分支或标记，可能会导致其他协作者工作时所基于的提交从分支或标记的历史记录中删除。 这可能会导致合并冲突或拉取请求损坏。 强制推送还可用于删除分支或将分支指向拉取请求中未批准的提交。

启用强制推送不会覆盖任何其他规则。 例如，如果分支需要线性提交历史记录，则无法强制推送合并提交到该分支。

需要 code scanning 结果

如果存储库配置了 code scanning，则当满足以下条件之一时，可以使用规则集来防止合并拉取请求：

  • 某个必需的工具发现了一个 code scanning 警报，且该警报的严重程度符合规则集中的定义。
  • 所需的工具分析仍在进行中。
  • 未为存储库配置所需的工具。

有关详细信息，请参阅“设置代码扫描合并保护”。 有关 code scanning 的更多常规信息，请参阅“关于代码扫描”。

要求在合并之前通过工作流

可以在组织或企业级别配置规则集工作流，要求工作流在合并拉取请求之前传递。 有关详细信息，请参阅“创建组织中存储库的规则集”。

有关对常见规则集工作流配置设置进行故障排除的详细信息，请参阅 排查规则。

使用工作流文件

要使用此规则，必须首先创建工作流文件。 工作流文件所在的存储库需要符合要在其中运行该文件的存储库可见性要求。 具体而言，公共工作流可以在组织中的任何存储库上运行，内部工作流只能在内部和专用存储库上运行，专用工作流只能在专用存储库上运行。 有关详细信息，请参阅“工作流”。

如果工作流文件位于内部或专用存储库中，并且需要在组织的其他存储库中使用该工作流，则需要允许从存储库外部访问该工作流。 有关详细信息，请参阅允许访问内部存储库中的组件或允许访问专用存储库中的组件。

将此规则添加到规则集时，请在组织设置中指定要强制实施的源存储库和工作流。

对规则集工作流使用“评估”模式

如果规则集工作流在“评估”模式下运行并通过，则可以将规则集工作流设置为“活动”模式并合并拉取请求，而不会触发新的工作流运行。

如果在“评估”模式下创建规则集之前打开拉取请求，则仍可以合并拉取请求，因为不会强制执行规则集。

有关强制状态的详细信息，请参阅创建存储库的规则集。

支持的事件触发器

规则集工作流支持使用 pull_request、pull_request_target 和 merge_group 事件。 因此，必须在工作流 on: 部分中指定一个或多个此类事件，以便由规则集运行工作流。

为支持的事件指定的任何筛选器都会被忽略，例如，branches、branches-ignore、paths 和 types 等。 工作流仅由受支持事件的默认活动类型触发，并且始终由受支持事件的默认活动类型触发。

活动默认活动类型
pull_requestopened, synchronize, reopened
pull_request_targetopened, synchronize, reopened
merge_groupchecks_requested

使用规则集工作流定位特定分支

应用此规则将阻止直接推送，因为规则集工作流作为拉取请求和合并队列体验的一部分运行。 因此，不应将此规则应用于以存储库中所有分支为目标的规则集。

此规则应仅添加到以分支为目标的规则集，其中对分支的所有更改都由拉取请求执行。

（可选）如果你希望允许创建分支而不考虑状态检查结果如何，则可以选择“创建时不需要工作流检查”。

元数据限制

使用 GitHub Enterprise 计划的组织可以通过访问更多规则来控制提交元数据的格式。 可以使用文本字符串或正则表达式语法来定义提交元数据必须符合的模式。 例如，可以要求提交消息包含 GitHub 问题号，或者提交者或作者的电子邮件地址以 @octoorg.com 结尾。 还可以控制新分支名称和标记名称的格式。 有关推荐的提交元数据的有用正则表达式，请参阅 创建存储库的规则集。

如果参与者尝试使用不符合要求的提交来更新分支或标记，参与者将看到一条错误消息，告知他们提交有何错误。 此错误可能在以下两处显示：用户推送时出现在命令行中，用户尝试提交或合并拉取请求时出现在 GitHub.com 上。 提交在 Git 中是不可变的：一旦参与者创建了提交，他们便无法编辑提交的元数据，因此他们有可能需要进行变基以使用新提交来重写提交历史记录，才能将内容成功贡献到存储库。

元数据限制可用于在分支的历史记录中强制实现提交之间的一致性。 如果要强制遵循最佳做法（如常规提交规范）或与依赖于提交元数据的工具进行集成，这可能会很有用。 例如，如果每条消息都符合可预测的格式，则更容易根据提交消息的内容运行脚本。

有关元数据限制的重要注意事项

元数据限制会阻止“引用更新”。 如果参与者推送的工作包含不符合要求的提交，推送不会被拒绝，但其所面向的分支或标记不会更新。 从技术上讲，提交仍会进入存储库：提交将“可检索”（可以在存储库导航到提交），但无法“访问”（它们未连接到分支或标记的历史记录）。 如果参与者的推送还包括其他分支或标记的工作以及满足这些分支或标记要求的提交，则这些引用将成功更新。

元数据限制可能会为参与存储库的人员带来不便。 通常，如果施加元数据限制，则应对有限的一组分支执行此操作，以避免影响参与者的日常工作。 例如，不应要求参与者可能处理的任何主题分支上提交消息的一致性，而应仅在 main 上要求提交消息的一致性，然后要求将请求拉取到 main。

如果使用 Squash 合并，则会忽略拉取请求中的单个提交。 相反，仅对生成的单个合并提交的元数据验证限制。 拉取请求页面会在允许合并前验证此信息，确保最终提交合规。 对于应用到提交者电子邮件的元数据限制，该模式还必须包括 noreply@github.com 以确保 Squash 合并满足限制。

向现有分支或标记添加元数据限制时，将针对从该点以后推送到该分支或标记的新提交强制执行规则，但不针对分支或标记的现有历史记录强制执行这些规则。

限制文件路径

阻止将包含指定文件路径更改的提交推送到存储库。 限制为 200 个条目，每个条目最多 200 个字符。

可以为此使用 fnmatch 语法。 例如，针对 test/demo/**/* 的限制可阻止对 test/demo/ 目录中的文件或文件夹进行任何推送。 针对 test/docs/pushrules.md 的限制可阻止对 pushrules.md 目录中 test/docs/ 文件的专门推送。 有关详细信息，请参阅“创建存储库的规则集”。

限制文件路径长度

阻止将包含超过指定字符限制的文件路径的提交推送到存储库。

限制文件扩展名

阻止将包含具有指定文件扩展名的文件的提交推送到存储库。 限制为 200 个条目，每个条目最多 200 个字符。

限制文件大小

阻止将超过指定文件大小限制的提交推送到存储库。