About rulesets

About rulesets

A ruleset is a named list of rules that applies to a repository, or to multiple repositories in an organization. You can have up to 75 rulesets per repository, and 75 organization-wide rulesets.

When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with a certain role, such as repository administrator, or it can be specific teams or GitHub Apps. For more information about granting bypass permissions, see 创建存储库的规则集.

For organizations on the GitHub Enterprise plan, you can set up rulesets at the enterprise or organization level to target multiple repositories in your organization. See 管理组织中存储库的规则集.

You can use rulesets to target branches or tags in a repository or to block pushes to a repository and the repository's entire fork network.

借助推送规则集委派绕过功能，可以控制谁可以绕过推送保护以及应允许哪些被阻止的推送。

启用委派绕过后，存储库的参与者在推送包含受限内容的提交时必须请求“绕过特权”。 请求将发送到指定的审阅者组，他们批准或拒绝绕过推送规则的请求。

如果绕过推送规则的请求获得批准，则参与者可以推送包含受限内容的提交。 如果请求被拒绝，则参与者必须首先从包含受限内容的提交中移除相关内容，然后才能再次推送。

若要配置委派绕过，组织所有者或存储库管理员首先会创建“绕过列表”。 绕过列表包括特定角色和团队，例如安全团队或存储库管理员，他们负责监督绕过推送保护的请求。 有关详细信息，请参阅 管理组织中存储库的规则集 和 关于规则集。

Branch and tag rulesets

You can create rulesets to control how people can interact with selected branches and tags in a repository. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. For example, you could set up a ruleset for your repository's feature branch that requires signed commits and blocks force pushes for all users except repository administrators.

For each ruleset you create, you specify which branches or tags in your repository, or which repositories in your organization, the ruleset applies to. You can use fnmatch syntax to define a pattern to target specific branches, tags, and repositories. For example, you could use the pattern releases/**/* to target all branches in your repository whose name starts with the string releases/. For more information on fnmatch syntax, see 创建存储库的规则集.

Push rulesets

使用推送规则集，可以阻止对专用或内部存储库的推送，以及对此存储库整个分支网络的推送，具体取决于文件扩展名、文件路径长度、文件和文件夹路径以及文件大小。

推送规则不需要针对任何分支，因为它们会应用于对存储库的每条推送。

推送规则集允许你：

• 限制文件路径：阻止推送包含指定文件路径更改的提交。

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

• 限制文件路径长度：阻止推送包含超过指定字符限制的文件路径的提交。

• 限制文件扩展名：阻止推送包含具有指定文件扩展名的文件的提交。

• 限制文件大小：阻止推送超过指定文件大小限制的提交。

关于向已创建分支的存储库推送规则集

推送规则适用于存储库的整个分支网络，以确保存储库的每个入口点均受到保护。 例如，如果将已启用推送规则集的存储库创建为分支，则相同的推送规则集也适用于已创建分支的存储库。

对于已创建分支的存储库，只有对推送规则具有旁路权限的人员是根存储库中具有旁路权限的人员。

About rulesets and protected branches

Rulesets work alongside any branch protection rules in a repository. Many of the rules you can define in rulesets are similar to protection rules, and you can start using rulesets without overriding any of your existing protection rules.

Rulesets have the following advantages over branch protection rules.

• Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a branch in your repository will be evaluated when someone interacts with that branch. See About rule layering.
• Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets.
• Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository.
• You can create additional rules to control the metadata of commits entering a repository, such as the commit message and the author's email address. See 规则集的可用规则."

Using ruleset enforcement statuses

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

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

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

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

About rule layering

A ruleset does not have a priority. Instead, if multiple rulesets target the same branch or tag in a repository, the rules in each of these rulesets are aggregated. If the same rule is defined in different ways across the aggregated rulesets, the most restrictive version of the rule applies. As well as layering with each other, rulesets also layer with protection rules targeting the same branch or tag.

For example, consider the following situation for the my-feature branch of the octo-org/octo-repo repository.

• An administrator of the repository has set up a ruleset targeting the my-feature branch. This ruleset requires signed commits, and three reviews on pull requests before they can be merged.
• An existing branch protection rule for the my-feature branch requires a linear commit history, and two reviews on pull requests before they can be merged.
• An administrator of the octo-org organization has also set up a ruleset targeting the my-feature branch of the octo-repo repository. The ruleset blocks force pushes, and requires one review on pull requests before they can be merged.

The rules from each source are aggregated, and all rules apply. Where multiple different versions of the same rule exist, the result is that the most restrictive version of the rule applies. Therefore, the my-feature branch requires signed commits and a linear commit history, force pushes are blocked, and pull requests targeting the branch will require three reviews before they can be merged.

Next steps

Next, learn how to communicate important information with members of your enterprise using READMEs. See Create a README for your enterprise.