# 关于受保护分支

您可以通过设置分支保护规则来保护重要分支，这些规则定义协作者是否可以删除或强制推送到分支以及设置任何分支推送要求，例如通过状态检查或线性提交历史记录。

## 关于分支保护规则

> \[!TIP] 如果使用需要特定状态检查的分支保护规则，请确保所有工作流的作业名称都是唯一的。 在多个工作流中使用相同的作业名称可能会导致状态检查结果不明确，并阻止合并拉取请求。 请参阅“[状态检查](/zh/enterprise-server@3.21/pull-requests/reference/status-checks)”。

在协作者可以推送更改到您的仓库分支之前，您可以通过创建分支保护规则来实施特定的工作流程或要求，包括将拉取请求合并到分支。 仅当存储库属于组织时，才能将参与者添加到绕过列表。

默认情况下，每个分支保护规则都禁止强制推送到匹配的分支并阻止删除匹配的分支。 您可以选择禁用这些限制并启用其他分支保护设置。

默认情况下，分支保护规则的限制不适用于对存储库具有管理员权限的人员或具有“绕过分支保护”权限的自定义角色。 也可以选择将限制应用于具有“绕过分支保护”权限的管理员和角色。 有关详细信息，请参阅“[管理组织的自定义存储库角色](/zh/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization)”。

可以在存储库中为特定分支、所有分支或者与使用 `fnmatch` 语法指定的命名模式匹配的任何分支创建分支保护规则。 例如，若要保护包含单词 `release` 的任何分支，可以为 `*release*` 创建分支规则。 有关分支名称模式的详细信息，请参阅 [管理分支保护规则](/zh/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)。

您可以将拉取请求配置为在满足所有合并要求时自动合并。 有关详细信息，请参阅“[自动合并拉取请求](/zh/enterprise-server@3.21/pull-requests/how-tos/merge-and-close-pull-requests/automatically-merging-a-pull-request)”。

> \[!NOTE]
> 一次只能应用一个分支保护规则，这意味着当一个规则的多个版本面向同一分支时，很难知道将应用哪个规则。
> 此外，你可能想要创建一组适用于组织中的多个存储库的规则。
> 此限制不适用于规则集，请参阅 [关于规则集](/zh/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)。

## 关于分支保护设置

对于每个分支保护规则，您可以选择启用或禁用以下设置。

* [在合并前需要审核拉取请求](#require-pull-request-reviews-before-merging)
* [合并前必需状态检查](#require-status-checks-before-merging)
* [合并前需要解决对话中的问题](#require-conversation-resolution-before-merging)
* [需要签名提交](#require-signed-commits)
* [需要线性历史记录](#require-linear-history)
* [需要合并队列](#require-merge-queue)
* [要求部署在合并前成功](#require-deployments-to-succeed-before-merging)
* [锁定分支](#lock-branch)
* [不允许绕过上述设置](#do-not-allow-bypassing-the-above-settings)
* [限制可推送到匹配分支的人员](#restrict-who-can-push-to-matching-branches)
* [允许强制推送](#allow-force-pushes)
* [允许删除](#allow-deletions)

有关如何设置分支保护的详细信息，请参阅“[管理分支保护规则](/zh/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)”。

### 合并前要求对拉取请求进行审查

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

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

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

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

如果协作者尝试将待处理或被拒绝审查的拉取请求合并到受保护分支，则该协作者将收到错误消息。

```shell
remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes have been requested.
```

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

（可选）你可以限制特定人员或团队忽略拉取请求审查的权限。 有关详细信息，请参阅“[忽略拉取请求审查](/zh/enterprise-server@3.21/pull-requests/how-tos/review-pull-requests/dismissing-a-pull-request-review)”。

（可选）您可以选择要求代码所有者进行审查。 如果这样做，则任何影响代码的拉取请求都必须得到代码所有者的批准，才能合并到受保护分支。

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

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

> \[!NOTE] 如果选择“**推送新提交时关闭旧拉取请求审批**”和/或“**需要审批最近的可评审推送**”，则手动为拉取请求创建合并提交并将其直接推送到受保护分支的操作将失败，除非合并内容与 GitHub 为拉取请求生成的合并完全匹配。
>
> 此外，使用这些设置，如果合并基在提交评审后引入新更改，审批评审将因过时而被关闭。 合并基础是主题分支和基础分支之间的最后一个共同上级的提交。 如果合并基发生更改，则拉取请求在再次审批工作之前无法合并。

### 合并前必须进行状态检查

必需状态检查必须具有 `successful`、`skipped` 或 `neutral` 状态，协作者才能对受保护分支进行更改。 必需状态检查可以是检查或提交状态。 有关详细信息，请参阅“[状态检查](/zh/enterprise-server@3.21/pull-requests/reference/status-checks)”。

可以使用提交状态 API 让外部服务能够将提交标记为适当的状态。 有关详细信息，请参阅“[提交状态的 REST API 端点](/zh/enterprise-server@3.21/rest/commits/statuses)”。

启用必需状态检查后，必须通过所有必需状态检查，协作者才能将更改合并到受保护分支。 所有必需状态检查通过后，必须将任何提交推送到另一个分支，然后合并或直接推送到受保护分支。

任何人或对仓库具有写入权限的任何集成都可以设置仓库中任何状态检查的状态，但在某些情况下，你可能只想接受来自特定 GitHub App 的状态检查。 添加所需的状态检查时，可以选择最近将此检查设置为预期状态更新源的应用。 如果状态由任何其他人员或集成设置，则无法合并。 如果选择“任何来源”，您仍然可以手动验证合并框中列出的每个状态的作者。

您可以将必需状态检查设置为“宽松”或“严格”。 您选择的必需的状态检查类型将决定您的分支在合并之前是否需要与基础分支保持同步。

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

有关故障排除信息，请参阅 [必需状态检查故障排除](/zh/enterprise-server@3.21/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks)。

### 在合并前需要解决对话中的问题

在合并到受保护的分支之前，所有对拉取请求的评论都需要解决。 这确保所有评论在合并前都得到解决或确认。

### 需要签名提交

在分支上启用必需的提交签名后，贡献者  只能向该分支推送已签名并通过验证的提交。 有关详细信息，请参阅“[关于提交签名验证](/zh/enterprise-server@3.21/authentication/managing-commit-signature-verification/about-commit-signature-verification)”。

> \[!NOTE]

> 如果协作者将未签名的提交推送到要求提交签名的分支，则协作者需要对提交进行变基（rebase），以包括已验证的签名，然后将重写的提交强制推送到分支。

如果提交已签名并已验证，则可以将本地提交推送到分支。

但是，您不能将拉取请求合并到 GitHub 上的分支中。

可以在 合并，但必须在将请求推送到分支之前对生成的提交进行签名。 如果另一项保护规则要求必须通过拉取请求进行更改，你可能还需要具备绕过该限制的权限，才能推送在本地合并后生成的提交。 请参阅 [在本地检查拉取请求](/zh/enterprise-server@3.21/pull-requests/how-tos/review-pull-requests/checking-out-pull-requests-locally) 和 [对提交签名](/zh/enterprise-server@3.21/authentication/managing-commit-signature-verification/signing-commits)。

### 需要线性历史记录

强制实施线性提交历史记录可阻止协作者将合并提交推送到分支。 这意味着合并到受保护分支的任何拉取请求都必须使用压缩合并或变基合并。 严格的线性提交历史记录可以帮助团队更容易回溯更改。 有关合并方法的详细信息，请参阅 [合并拉取请求](/zh/enterprise-server@3.21/pull-requests/reference/pull-request-merges)。

在需要线性提交历史记录之前，存储库必须允许压缩合并或变基合并。 有关详细信息，请参阅“[配置拉取请求合并](/zh/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges)”。

### 要求合并队列

合并队列通过将拉取请求自动合并到繁忙的分支中，并确保分支永远不会因不兼容的更改而中断，从而帮助提高速度。

合并队列提供与“要求分支在合并之前保持最新”分支保护相同的优势，但不需要拉取请求作者在尝试合并之前，更新其拉取请求分支并等待状态检查完成。

如果分支具有每天从许多不同用户合并的大量拉取请求，那么使用合并队列特别有用。

拉取请求通过所有必需的分支保护检查后，对存储库具有写入访问权限的用户可以将该拉取请求添加到该队列。 合并队列将确保拉取请求的更改在应用于最新版本的目标分支和队列中已有的任何拉取请求时通过所有必需的状态检查。

合并队列可以使用 GitHub Actions 或你自己的 CI 提供程序对合并队列中的拉取请求运行所需的检查。 有关详细信息，请参阅“[GitHub Actions 文档](/zh/enterprise-server@3.21/actions)”。

一旦通过了所有必需的 CI 检查，GitHub 将根据分支保护中配置的合并策略合并拉取请求。
有关合并队列的详细信息，请参阅“[管理合并队列](/zh/enterprise-server@3.21/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)”。

### 在合并前要求部署成功

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

### 锁定分支

锁定分支将分支设为只读，确保无法对分支进行任何提交。 锁定的分支同样无法删除。

默认情况下，分支存储库不支持从其上游存储库同步。 可以启用“允许分支同步”以从上游存储库中提取更改，同时阻止对分叉分支的其他贡献。

### 不允许绕过上述设置

默认情况下，分支保护规则的限制不适用于对存储库具有管理员权限的人员或在存储库中具有“绕过分支保护”权限的自定义角色。

也可以启用此设置以将限制应用于具有“绕过分支保护”权限的管理员和角色。 有关详细信息，请参阅“[管理组织的自定义存储库角色](/zh/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization)”。

### 限制谁可以推送到匹配的分支

启用分支限制时，只有已授予权限的用户、团队或应用程序才能推送到受保护的分支。 您可以在受保护分支的设置中查看和编辑对受保护分支具有推送权限的用户、团队或应用程序。 当需要状态检查时，如果所需的检查失败，仍会阻止有权推送到受保护分支的人员、团队和应用合并为一个分支。 当需要拉取请求时，有权推送到受保护分支的人员、团队和应用仍需要创建拉取请求。

（可选）可以将相同的限制应用于创建与规则匹配的分支。 例如，如果创建一个仅允许特定团队推送到包含单词 `release` 的任何分支的规则，则只有该团队的成员才能创建包含单词 `release` 的新分支。

只能向对存储库具有写入权限的用户、团队或已安装的 GitHub Apps 授予推送到受保护分支或创建匹配分支的权限。 对存储库具有管理员权限的人员和应用程序始终能够推送到受保护分支或创建匹配分支。

### 允许强制推送

默认情况下，GitHub 会阻止对所有受保护分支的强制推送。 当您启用对受保护分支的强制推送时，您可以选择两个可以强制推送的组中的一个：

1. 允许至少具有存储库写入权限的每个人强制推送到分支，包括具有管理员权限的人员。
2. 仅允许特定人员或团队强制推送到分支。

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

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

如果站点管理员已阻止强制推送到存储库中的所有分支，则无法为受保护的分支启用强制推送。 有关详细信息，请参阅“[在企业中实施仓库管理策略](/zh/enterprise-server@3.21/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)”。

如果站点管理员已阻止强制推送到默认分支，你仍然可以为任何其他受保护的分支启用强制推送。

### 允许删除

默认情况下，您不能删除受保护的分支。 启用删除受保护分支后，任何对仓库至少拥有写入权限的人都可以删除分支。

> \[!NOTE]
> 如果分支已锁定，即使你有权删除分支，也无法将其删除。