Enforcing code governance in your enterprise with rulesets

Introduction

You can create rulesets to control how users can interact with code in repositories across your enterprise. You can:

• Create a branch or tag ruleset to control things like who can push commits to a certain branch, how commits must be formatted, or who can delete or rename a tag.
• Create a push ruleset to block pushes to a private or internal repository and the repository's entire fork network. Push rulesets allow you to block pushes based on file extensions, file path lengths, file and folder paths, and file sizes.

To learn more, see 关于规则集.

Importing prebuilt rulesets

To import a prebuilt ruleset created by GitHub, see github/ruleset-recipes.

可以使用 JSON 文件从另一个存储库或组织导入规则集。 如果要将相同规则集应用于多个存储库或组织，这种方法很有用。 For more information, see "管理组织中存储库的规则集."

How will I define where my ruleset applies?

Rulesets allow you to flexibly target the organizations, repositories, and branches where you want rules to apply.

• To target organizations, you can select all, choose from a list, or define a dynamic pattern for organization names using fnmatch syntax. For syntax details, see 创建存储库的规则集.
• Within those organizations, you can target all repositories, or target a dynamic list by custom property. See 管理组织中存储库的自定义属性.
• Within the repositories, you can target certain branches or tags: all branches, the default branch, or a dynamic list using fnmatch syntax.

When you create a ruleset that targets branches in a repository, repository administrators can no longer rename branches or change the default branch in the targeted repository. They can still create and delete branches if they have the appropriate permissions.

How can I control the format of commits?

In branch or tag rulesets, you can add a rule that restricts the format of commit metadata such as commit message or author email.

If you select Must match a given regex pattern restriction, you can use regular expression syntax to define patterns that the metadata must or must not match. For syntax details and examples, see 创建存储库的规则集.

Using ruleset enforcement statuses

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

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

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

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

Creating a branch or tag ruleset

1. 在 GitHub 的右上角，单击你的个人资料照片。

2. 根据环境，单击“你的企业”，或单击“你的企业”，然后单击要查看的企业********。

3. 在页面左侧的企业帐户边栏中，单击 “策略”。

4. Under "Policies", click Code.

5. 单击“添加规则集”。****

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

7. 或者，若要创建针对标签的规则集，请单击“新建标签规则集”****。

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

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

Granting bypass permissions for your branch or tag ruleset

You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset.

The following are eligible for bypass access:

• Repository admins, organization owners, and enterprise owners
• The maintain or write role, or deploy keys.

1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.

2. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.

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

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

Choosing which organizations to target in your enterprise

Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use Enterprise Managed Users, you can also choose to target all repositories owned by users in your enterprise.

If you set a dynamic list, you'll add one or more naming patterns using fnmatch syntax. For example, the string *open-source would match any organization with a name that ends with open-source. For syntax details, see "创建存储库的规则集."

Choosing which repositories to target in your enterprise

Within the selected organizations, you can target all repositories or target a dynamic list by custom property. See 管理组织中存储库的自定义属性.

Choosing which branches or tags to target

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

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

Selecting branch or tag protections

In the "Branch protections" or "Tag protections" section, select the rules you want to include in the ruleset. When you select a rule, you may be able to enter additional settings for the rule. For more information on the rules, see "规则集的可用规则"

Adding metadata restrictions

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

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

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

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

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

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

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

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

Finalizing your branch or tag ruleset and next steps

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

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

Creating a push ruleset

You can create a push ruleset for private or internal repositories in your enterprise.

1. 在 GitHub 的右上角，单击你的个人资料照片。
2. 根据环境，单击“你的企业”，或单击“你的企业”，然后单击要查看的企业********。
3. In the left sidebar, in the "Policies" section, click Code.
4. Click New ruleset.
5. Click New push ruleset.
6. Under "Ruleset name," type a name for the ruleset.
7. Optionally, to change the default enforcement status, click Disabled and select an enforcement status. For more information about enforcement statuses, see 关于规则集

Granting bypass permissions for your push ruleset

You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. The following are eligible for bypass access:

• Repository admins, organization owners, and enterprise owners
• The maintain or write role, or deploy keys

1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click Add bypass.
2. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected.

Choosing which organizations to target in your enterprise

Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use Enterprise Managed Users, you can also choose to target all repositories owned by users in your enterprise.

If you set a dynamic list, you'll add one or more naming patterns using fnmatch syntax. For example, the string *open-source would match any organization with a name that ends with open-source. For syntax details, see "创建存储库的规则集."

Choosing which repositories to target in your enterprise

Within your chosen organizations, you can target all repositories, or target a dynamic list using custom properties. See 管理组织中存储库的自定义属性.

Selecting push protections

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

配置的任何推送保护都会阻止此存储库中的推送，并在此存储库的整个分支网络中阻止推送。

1. 在“推送保护”下，单击你要应用的限制。 然后填写你所选限制的详细信息。

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

Finalizing your push ruleset and next steps

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

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