规则集的可用规则

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

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

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

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

限制创建

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

限制更新

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

限制删除

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

需要线性历史记录

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

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

需要合并队列

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

其他设置

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

• 合并方法：合并拉取请求中的更改时使用的方法。
• 生成并发：限制请求检查和工作流同时运行的排队拉取请求的数量。
  • 此设置控制合并队列何时调度 merge_group.checks_requested webhook 事件，该事件会触发配置为在 merge_group 上运行的 GitHub Actions 工作流。 有关详细信息，请参阅“Webhook 事件和有效负载”。
  • 例如，如果队列中添加了 5 个拉取请求，并且构建并发设置为 3，则合并队列将为前 3 个拉取请求调度 checks_requested 事件。 当收到这些拉取请求之一的结果时，合并队列将为第四个拉取请求调度事件，依此类推。
• 最小/最大组大小：将合并到一个组中的拉取请求的数量。
• 满足最小组大小的等待时间（分钟）：将第一个拉取请求添加到队列后，合并队列将等待的时间，以满足最小组大小。 这段时间后，最小组大小将被忽略，较小的组将被合并。
• 要求所有队列条目通过所需的检查：
  • 启用此设置后，合并组中的每个项目都必须通过所有必需的检查。
  • 禁用此设置时，只有合并组头部的提交（即包含组中所有拉取请求的更改的提交）必须通过合并所需的检查。
• 状态检查超时（分钟）：报告结论所需的状态检查的最长时间。 经过这么长时间后，未报告结论的检查将被视为失败

在合并前要求部署成功

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

要求签名提交

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

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

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

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

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

在合并前需要拉取请求

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

其他设置

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

设置 code scanning 合并保护

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

• 所需工具发现了一个 code scanning 警报，其严重性是在规则集中定义的。

• 所需 code scanning 工具的分析仍在进行中。

• 未为存储库配置所需的 code scanning 工具。

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

阻止强制推送

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

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

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

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

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

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

使用工作流文件

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

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

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

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

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

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

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

支持的事件触发器

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

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

活动	默认活动类型
pull_request	.- .
pull_request_target	.- .
merge_group	checks_requested

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

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

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

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

元数据限制

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

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

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

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

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

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

如果使用 Squash 合并，则应注意在合并之前评估元数据限制，因此拉取请求上的所有提交都必须满足要求。 对于应用到提交者电子邮件的元数据限制，该模式还必须包括 noreply@github.com 以确保 Squash 合并满足限制。

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

限制文件路径

阻止将包含指定文件路径更改的提交推送到存储库。

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

限制文件路径长度

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

限制文件扩展名

阻止将包含具有指定文件扩展名的文件的提交推送到存储库。

限制文件大小

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