Skip to main content

规则集的可用规则

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

谁可以使用此功能?

对存储库具有读取访问权限的任何人都可以查看存储库的规则集。 对存储库具有管理员访问权限的人员或者具有“编辑存储库规则”权限的自定义角色可以为存储库创建、编辑和删除规则集。

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

推送规则集适用于内部存储库和专用存储库中的 GitHub Team 计划,以及已启用推送规则集的存储库分支。

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

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

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

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

限制创建

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

限制更新

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

限制删除

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

需要线性历史记录

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

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

在合并前要求部署成功

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

要求签名提交

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

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

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

Note

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

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

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

在合并前需要拉取请求

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

其他设置

Note

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

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

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

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

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

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

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

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

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

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

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

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

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

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

启用必需的状态检查后,必须通过所有必需的状态检查,协作者才能将更改合并到分支或标记。

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

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

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

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

设置 code scanning 合并保护

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

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

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

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

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

阻止强制推送

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

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

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

限制文件路径

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

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

限制文件路径长度

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

限制文件扩展名

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

限制文件大小

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