本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 拉取请求评论批准
<a name="pull-request-build-policy"></a>

CodeBuild 支持拉取请求构建策略，这些策略可对由拉取请求触发的构建提供额外的控制。您可能不想自动构建来自未知用户的拉取请求，直到可以审查其更改。此功能可让您要求一名团队成员先审查代码，然后运行管道。这通常用作在构建未知贡献者提交的代码时的安全措施。

拉取请求构建策略允许您根据贡献者的权限和批准状态控制何时为拉取请求生成 CodeBuild 触发器。这对于公共存储库或接受外部协作者贡献的存储库尤为重要。

启用后，此功能可确保只有在以下任一情况下，才会为拉取请求触发构建：
+ 拉取请求由可信贡献者创建。
+ 可信贡献者通过发布特定评论来批准拉取请求。

## 工作原理
<a name="pull-request-build-policy.how-it-works"></a>

**可信贡献者**  
可信贡献者是指源代码控制系统中的当前角色在基于拉取请求的策略中设置为批准者角色的用户。当受信任的贡献者创建拉取请求时，会自动 CodeBuild 触发构建，保持当前行为。

**不可信贡献者**  
不可信贡献者是指其角色未在批准者角色列表中设置的用户。当不可信贡献者创建拉取请求时：  

1. CodeBuild 将构建状态标记为 “失败”，并显示消息 “启动构建需要拉取请求批准”。

1. 可信贡献者必须审核更改并使用 `/codebuild_run(<SHA_OF_THE_LATEST_COMMIT>)` 发布评论才能触发构建。例如 `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)`。

1. CodeBuild 验证评论者的权限，并在获得批准后触发构建。

1. 构建结果将在拉取请求页面上报告。

**评论批准语法**  
可信贡献者可以使用以下评论格式批准构建：  
+ `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)`：基于指定的提交 SHA 触发构建。

## 配置
<a name="pull-request-build-policy.configuration"></a>

**默认 行为**  
默认情况下，所有新创建的 CodeBuild 项目均启用拉取请求构建策略。

**API 参数**  
拉取请求构建策略是在以下操作中使用 `PullRequestBuildPolicy` 参数配置的：  
+ `CreateWebhook`
+ `UpdateWebhook`

**`PullRequestBuildPolicy` 结构**  

```
{
    "requiresCommentApproval": "string",
    "approverRoles": ["string", ...]
}
```

**`requiresCommentApproval`**  
指定在对拉取请求触发构建之前，何时需要基于评论的批准。此设置决定构建是自动运行，还是需要通过评论进行明确批准。  
类型：字符串  
有效值：  
+ `DISABLED`：无需评论批准即可自动触发构建。
+ `FORK_PULL_REQUESTS`：只有来自分叉存储库的拉取请求才需要评论批准（除非贡献者是批准者角色之一）。
+ `ALL_PULL_REQUESTS`：所有拉取请求在构建执行之前都需要评论批准（除非贡献者是批准者角色之一）。这是默认值。

**`approverRoles`**  
当需要评论批准时，对拉取请求构建具有批准权限的存储库角色列表。只有拥有这些角色的用户才能提供有效的评论批准。如果拉取请求贡献者是这些角色之一，则其拉取请求构建将自动触发。  
类型：字符串数组  
 GitHub 项目的有效值（这些值映射到 GitHub 角色）：  
+ `GITHUB_ADMIN`：存储库管理员
+ `GITHUB_MAINTAIN`：存储库维护者
+ `GITHUB_WRITE`：具有写入权限的用户
+ `GITHUB_TRIAGE`：具有分类权限的用户
+ `GITHUB_READ`：具有读取权限的用户
+ 默认值：`["GITHUB_ADMIN", "GITHUB_MAINTAINER", "GITHUB_WRITE"]`
 GitLab 项目的有效值（这些值映射到 GitLab 角色）：  
+ `GITLAB_OWNER`：存储库所有者
+ `GITLAB_MAINTAINER`：存储库维护者
+ `GITLAB_DEVELOPER`：拥有开发人员权限的用户
+ `GITLAB_REPORTER`：具有报告者权限的用户
+ `GITLAB_PLANNER`：拥有计划者权限的用户
+ `GITLAB_GUEST `：拥有访客权限的用户
+ 默认值：`["GITLAB_OWNER", "GITLAB_MAINTAINER", "GITLAB_DEVELOPER"]`
Bitbucket 项目的有效值（这些值映射到 Bitbucket 角色）：  
+ `BITBUCKET_ADMIN `：存储库管理员
+ `BITBUCKET_WRITE`：具有写入权限的用户
+ `BITBUCKET_READ `：具有读取权限的用户
+ 默认值：`["BITBUCKET_ADMIN", "BITBUCKET_WRITE"]`

## 示例
<a name="pull-request-build-policy.examples"></a>

**为所有拉取请求启用评论批准**  
要使用 AWS CodeBuild SDK 为 webhook 启用或禁用 Pull Request Build 策略，请使用`CreateWebhook`或 `UpdateWebhook` API 方法的请求语法中的`pullRequestBuildPolicy`字段。有关更多信息，请参阅《CodeBuild API Reference》**中的 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。  
拥有 Github 管理员角色、维护角色和写入角色的用户将被视为可信贡献者。  

```
"pullRequestBuildPolicy": {
    "requiresCommentApproval": "ALL_PULL_REQUESTS",
    "approverRoles": ["GITHUB_ADMIN", "GITHUB_MAINTAIN", "GITHUB_WRITE"]
}
```

**仅为存储库管理员和维护者启用评论批准**  
拥有 “管理员”、“维护” GitHub 角色的用户将被视为可信贡献者。  

```
"pullRequestBuildPolicy": {
    "requiresCommentApproval": "FORK_PULL_REQUESTS",
    "approverRoles": ["GITHUB_ADMIN", "GITHUB_MAINTAINER"]
}
```

**禁用评论批准**  

```
"pullRequestBuildPolicy": { 
    "requiresCommentApproval": "DISABLED"
}
```

## AWS CloudFormation
<a name="pull-request-build-policy.cloudformation"></a>

要使用 AWS CloudFormation 模板为 webhook 启用或禁用 Pull Request Build 策略，请使用 PullRequestBuildPolicy 属性。 AWS CloudFormation 模板中以下 YAML 格式的部分创建了一个带有 webhook 的项目，该挂钩已为所有拉取请求启用拉取请求构建策略。将维护角色和管理员角色指定为批准者。

```
CodeBuildProject:
  Type: AWS::CodeBuild::Project
  Properties:
    Name: MyProject
    ServiceRole: service-role
    Artifacts:
      Type: NO_ARTIFACTS
    Environment:
      Type: LINUX_CONTAINER
      ComputeType: BUILD_GENERAL1_SMALL
      Image: aws/codebuild/standard:5.0
    Source:
      Type: BITBUCKET
      Location: source-location
    Triggers:
      Webhook: true
      FilterGroups:
        - - Type: EVENT
            Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED
          - Type: BASE_REF
            Pattern: ^refs/heads/main$
            ExcludeMatchedPattern: false
      PullRequestBuildPolicy:
        RequiresCommentApproval: ALL_PULL_REQUESTS
        ApproverRoles:
          - GITHUB_MAINTAIN
          - GITHUB_ADMIN
```

## 控制台配置
<a name="pull-request-build-policy.console"></a>

要使用 AWS 管理控制台筛选 webhook 事件，请执行以下操作：

1. 对于**评论批准**，请针对所有拉取请求 (`ALL_PULL_REQUEST`) 或仅针对来自分叉的拉取请求 (`FORK_PULL_REQUEST`) 选择已禁用或已启用。

1. 对于**批准者角色**，选择当需要评论批准时对拉取请求构建具有批准权限的存储库角色列表。

有关更多信息，请参阅《*CodeBuild API 参考*》中的[创建构建项目（控制台）](create-project.md#create-project-console)和[WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。

![\[主要源 webhook 事件控制台，带有评论批准。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-comment-approval.png)