本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 提取請求評論核准
<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 觸發建置。

## Configuration
<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 的提取請求建置政策，請使用 `CreateWebhook`或 `UpdateWebhook` API 方法請求語法中的 `pullRequestBuildPolicy` 欄位。如需詳細資訊，請參閱 *CodeBuild API 參考*中的 [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 角色的使用者 Admin， Maintain 將被視為信任的貢獻者。  

```
"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 的提取請求建置政策，請使用 PullRequestBuildPolicy 屬性。下列 an AWS CloudFormation 範本的 YAML 格式部分會建立具有 Webhook 的專案，該 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_tw/codebuild/latest/userguide/images/pull-request-comment-approval.png)