本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 将 web 挂钩与 AWS CodeBuild
AWS CodeBuild 支持 webhook 与 GitHub 企业服务器 GitHub GitLab、 GitLab 自助管理和 Bitbucket 集成。
**Topics**
+ [将 webhook 与以下各项配合使用的最佳实践 AWS CodeBuild](#webhook-best-practices)
+ [Bitbucket Webhook 事件](bitbucket-webhook.md)
+ [GitHub 全球和组织 webhook](github-global-organization-webhook.md)
+ [GitHub 手动 webhook](github-manual-webhook.md)
+ [GitHub webhook 事件](github-webhook.md)
+ [GitLab 群组 webhook](gitlab-group-webhook.md)
+ [GitLab 手动 webhook](gitlab-manual-webhook.md)
+ [GitLab webhook 事件](gitlab-webhook.md)
+ [Buildkite 手动 webhook](buildkite-manual-webhook.md)
+ [拉取请求评论批准](pull-request-build-policy.md)
## 将 webhook 与以下各项配合使用的最佳实践 AWS CodeBuild
对于使用公共存储库来设置 Webhook 的项目，我们建议使用以下选项：
设置 `ACTOR_ACCOUNT_ID` 筛选条件
将 `ACTOR_ACCOUNT_ID` 筛选条件添加到项目的 Webhook 筛选条件组可指定哪些用户可以触发构建。发送到的每个 webhook 事件都 CodeBuild 附带指定参与者标识符的发送者信息。 CodeBuild 将根据过滤器中提供的正则表达式模式过滤 webhook。您可以使用此筛选器指定允许触发构建的特定用户。有关更多信息，请参阅[GitHub webhook 事件](github-webhook.md)和[Bitbucket Webhook 事件](bitbucket-webhook.md)。
设置 `FILE_PATH` 筛选条件
将 `FILE_PATH` 筛选条件添加到项目的 Webhook 筛选条件组中，以包含或排除更改后可能触发构建的文件。例如，您可以使用正则表达式模式（例如 `^buildspec.yml$`）和 `excludeMatchedPattern` 属性来拒绝对 `buildspec.yml` 文件进行更改的构建请求。有关更多信息，请参阅[GitHub webhook 事件](github-webhook.md)和[Bitbucket Webhook 事件](bitbucket-webhook.md)。
缩小构建 IAM 角色的权限
由 Webhook 触发的构建使用项目中指定的 IAM 服务角色。我们建议将服务角色中的权限设置为运行构建所需的最低权限集。例如，在测试和部署场景中，创建一个用于测试的项目和另一个用于部署的项目。测试项目接受存储库中的 Webhook 构建，但不提供对您的资源的写入权限。部署项目提供对您的资源的写入权限，并且 Webhook 筛选条件配置为仅允许受信任的用户触发构建。
使用内联或 Amazon S3 存储的 buildspec
如果您自行在项目内定义内联 buildspec，或者将 buildspec 文件存储在 Amazon S3 存储桶中，则该 buildspec 文件仅对项目所有者可见。这样可以防止拉取请求对 buildspec 文件进行代码更改并触发不必要的构建。有关更多信息，请参阅 *CodeBuildAPI* 参考中的 [ProjectSource.buildspec](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-buildspec)。
# Bitbucket Webhook 事件
您可以使用 Webhook 筛选条件组来指定哪个 Bitbucket Webhook 事件触发构建。例如，您可以指定仅在对特定分支做出更改时触发构建。
您可以创建一个或多个 Webhook 筛选条件组，来指定哪些 Webhook 事件触发构建。如果任何筛选条件组评估为 true（即组中的所有筛选条件都评估为 true），则会触发构建。创建筛选条件组时，应指定：
**事件**
对于 Bitbucket，您可以选择以下一个或多个事件：
+ `PUSH`
+ `PULL_REQUEST_CREATED`
+ `PULL_REQUEST_UPDATED`
+ `PULL_REQUEST_MERGED`
+ `PULL_REQUEST_CLOSED`
webhook 的事件类型位于其在 `X-Event-Key` 字段中的标头中。下表显示了 `X-Event-Key` 标头值如何映射到事件类型。
如果您创建使用 `PULL_REQUEST_MERGED` 事件类型的 Webhook 筛选条件组，则必须在 Bitbucket Webhook 设置中启用 `merged` 事件。如果您创建使用 `PULL_REQUEST_CLOSED` 事件类型的 webhook 筛选条件组，则还必须在 Bitbucket webhook 设置中启用 `declined` 事件。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/bitbucket-webhook.html)
对于 `PULL_REQUEST_MERGED`，如果拉取请求与压缩策略合并且拉取请求分支已关闭，则原始的拉取请求提交将不再存在。在这种情况下，`CODEBUILD_WEBHOOK_MERGE_COMMIT` 环境变量包含压缩后的合并提交的标识符。
**一个或多个可选筛选条件**
使用正则表达式来指定筛选条件。对于触发构建的事件，组内与其关联的每个筛选条件都必须评估为 True。
`ACTOR_ACCOUNT_ID`（控制台中的 `ACTOR_ID`）
当 Bitbucket 账户 ID 与正则表达式模式匹配时，Webhook 事件会触发构建。此值显示在 Webhook 筛选条件负载中的 `actor` 对象的 `account_id` 属性中。
`HEAD_REF`
当头部引用与正则表达式模式（例如 `refs/heads/branch-name` 和 `refs/tags/tag-name`）匹配时，Webhook 事件会触发构建。`HEAD_REF` 筛选条件将评估分支或标签的 Git 引用名称。分支或标签名称显示在 Webhook 负载的 `push` 对象中的 `new` 对象的 `name` 字段中。对于拉取请求事件，分支名称显示在 Webhook 负载中的 `source` 对象的 `branch` 中的 `name` 字段中。
`BASE_REF`
当基础引用与正则表达式模式匹配时，Webhook 事件会触发构建。`BASE_REF` 筛选条件仅处理拉取请求事件（例如，`refs/heads/branch-name`）。`BASE_REF` 筛选条件评估分支的 Git 引用名称。分支名称显示在 `branch` 对象的 `name` 字段中，该对象位于 Webhook 负载的 `destination` 对象中。
`FILE_PATH`
当更改的文件的路径与正则表达式模式匹配时，Webhook 会触发构建。
`COMMIT_MESSAGE`
当 HEAD 提交消息与正则表达式模式匹配时，Webhook 会触发构建操作。
`WORKFLOW_NAME`
当工作流名称与正则表达式模式匹配时，Webhook 会触发构建操作。
**注意**
您可以在 Bitbucket 存储库的 webhook 设置中找到 webhook 负载。
**Topics**
+ [筛选 Bitbucket Webhook 事件（控制台）](bitbucket-webhook-events-console.md)
+ [筛选 Bitbucket Webhook 事件（开发工具包）](bitbucket-webhook-events-sdk.md)
+ [筛选 Bitbucket Webhook 事件 (CloudFormation)](bitbucket-webhook-events-cfn.md)
# 筛选 Bitbucket Webhook 事件（控制台）
要使用过滤 webhook 事件 AWS 管理控制台 ，请执行以下操作：
1. 创建项目时，选择**每次将代码更改推送到此存储库时都会重新构建**。
1. 从**事件类型**中，选择一个或多个事件。
1. 要在事件触发构建时进行筛选，请在**在这些条件下开始构建**下，添加一个或多个可选筛选条件。
1. 要在未触发事件时进行筛选，请在**在这些条件下不开始构建**下，添加一个或多个可选筛选条件。
1. 选择**添加筛选条件组**以添加另一个筛选条件组。
有关更多信息，请参阅《*AWS CodeBuild API 参考*》中的[创建构建项目（控制台）](create-project.md#create-project-console)和[WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
在此示例中，Webhook 筛选条件组仅针对拉取请求触发构建：
![\[一个 webhook 筛选条件组，仅针对拉取请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-bitbucket.png)
以两个筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/branch1!` 匹配的 HEAD 引用，指定在分支上创建或更新的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/branch1$` 匹配的 Git 引用名称，指定分支上的推送请求。
![\[两个筛选条件组的示例。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-bitbucket.png)
在此示例中，Webhook 筛选条件组会针对除标记事件之外的所有请求触发构建。
![\[一个 webhook 筛选条件组，针对除标记事件之外的所有请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-bitbucket.png)
在此示例中，仅当名称与正则表达式 `^buildspec.*` 匹配的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当文件名称与指定的正则表达式匹配时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)
在此示例中，仅当 `src` 或 `test` 文件夹中的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当指定文件夹中的文件发生更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex.png)
在此示例中，只有当其账户 ID 不与正则表达式 `actor-account-id` 匹配的 Bitbucket 用户进行更改时，Webhook 筛选条件组才会触发构建。
**注意**
有关如何查找你的 Bitbucket 账户 ID 的信息，请参阅 https://api.bitbucket.org/2.0/users/*user-name*，你的 Bitbucket 用户名在*user-name*哪里。
![\[一个 webhook 筛选条件组，仅当没有账户 ID 的 Bitbucket 用户进行更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-bitbucket.png)
在本示例中，当 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，Webhook 筛选条件组会触发推送事件的构建。
![\[一个 webhook 筛选条件组，当 HEAD 提交消息与正则表达式匹配时会触发推送事件的构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)
# 筛选 Bitbucket Webhook 事件（开发工具包）
要使用 AWS CodeBuild SDK 筛选 webhook 事件，请使用`CreateWebhook`或 `UpdateWebhook` API 方法的请求语法中的`filterGroups`字段。有关更多信息，请参阅《CodeBuild API Reference》**中的 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
要创建仅针对拉取请求触发构建的 Webhook 筛选条件，请在请求语法中插入以下内容：
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
}
]
]
```
要创建仅针对指定分支触发构建的 Webhook 筛选条件，请使用 `pattern` 参数指定用于筛选分支名称的正则表达式。以两个筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/myBranch$` 匹配的 HEAD 引用，指定在分支上创建或更新的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/myBranch$` 匹配的 Git 引用名称，指定分支上的推送请求。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_CLOSED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
},
{
"type": "BASE_REF",
"pattern": "^refs/heads/main$"
}
],
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
}
]
]
```
您可以使用 `excludeMatchedPattern` 参数指定不触发构建的事件。在此示例中，将针对除标记事件之外的所有请求触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/tags/.*",
"excludeMatchedPattern": true
}
]
]
```
您可以创建仅在帐户 ID 为 `actor-account-id` 的 Bitbucket 用户进行更改时触发构建的筛选条件。
**注意**
有关如何查找你的 Bitbucket 账户 ID 的信息，请参阅 https://api.bitbucket.org/2.0/users/*user-name*，你的 Bitbucket 用户名在*user-name*哪里。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
},
{
"type": "ACTOR_ACCOUNT_ID",
"pattern": "actor-account-id"
}
]
]
```
您可以创建只有当名称与 `pattern` 参数中的正则表达式匹配的文件发生更改时，才触发构建的筛选条件。在此示例中，筛选条件组指定仅当名称与正则表达式 `^buildspec.*` 匹配的文件更改时才触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^buildspec.*"
}
]
]
```
在此示例中，筛选条件组指定仅当 `src` 或 `test` 文件夹中的文件发生更改时，才会触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^src/.+|^test/.+"
}
]
]
```
您可以创建一个筛选条件，仅当 HEAD 提交消息与模式参数中的正则表达式匹配时才触发构建操作。在本示例中，筛选条件组指定仅当推送事件的 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，才触发构建操作。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "COMMIT_MESSAGE",
"pattern": "\[CodeBuild\]"
}
]
]
```
# 筛选 Bitbucket Webhook 事件 (CloudFormation)
要使用 CloudFormation 模板过滤 webhook 事件，请使用 AWS CodeBuild 项目的`FilterGroups`属性。 CloudFormation 模板的以下 YAML 格式的部分创建两个筛选条件组。当这两个筛选条件的其中一个或两个评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称，指定由账户 ID 不为 `12345` 的 Bitbucket 用户在分支上创建或更新的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/.*` 匹配的 Git 引用名称，指定在分支上创建的推送请求。
+ 第三个筛选条件组指定一个推送请求，其中包含与正则表达式 `\[CodeBuild\]` 匹配的 HEAD 提交消息。
```
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
- Type: ACTOR_ACCOUNT_ID
Pattern: 12345
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: HEAD_REF
Pattern: ^refs/heads/.*
- Type: FILE_PATH
Pattern: READ_ME
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: COMMIT_MESSAGE
Pattern: \[CodeBuild\]
- Type: FILE_PATH
Pattern: ^src/.+|^test/.+
```
# GitHub 全球和组织 webhook
您可以使用 CodeBuild GitHub 全局或组织 webhook 在 GitHub 组织或企业内任何存储库的 webhook 事件上启动构建。全局和组织 webhook 可与任何现有的 GitHub webhook 事件类型配合使用，并且可以通过在创建 webhook 时添加范围配置来进行配置。 CodeBuild 您还可以使用全局和组织 webhook 在其中[设置自托管的 Acti GitHub on 运行器，以便 CodeBuild在单个项目中](action-runner.md)接收来自多个存储库`WORKFLOW_JOB_QUEUED`的事件。
**Topics**
+ [设置全球或组织 GitHub webhook](github-global-organization-webhook-setup.md)
+ [筛选 GitHub 全局或组织 webhook 事件（控制台）](github-global-organization-webhook-events-console.md)
+ [筛选 GitHub 组织 webhook 事件 ()CloudFormation](github-organization-webhook-events-cfn.md)
# 设置全球或组织 GitHub webhook
设置全局或组织 GitHub webhook 的高级步骤如下。有关全局和组织 GitHub webhook 的更多信息，请参阅[GitHub 全球和组织 webhook](github-global-organization-webhook.md)。
1. 将项目的源位置设置为 `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`。
1. 在 webhook 的范围配置中，将范围设置为 `GITHUB_ORGANIZATION` 或 `GITHUB_GLOBAL`，具体取决于范围应该是组织还是[全局 webhook](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks)。有关更多信息，请参阅 [webhook 的类型](https://docs.github.com/en/webhooks/types-of-webhooks)。
1. 在 webhook 的范围配置过程中指定一个名称。对于组织 webhook，这是组织名称，对于全局 webhook，这是企业名称。
**注意**
如果项目的源类型为 `GITHUB_ENTERPRISE`，则还需要在 webhook 范围配置过程中指定一个域。
1. （可选）如果您只想接收组织或企业内特定存储库的 webhook 事件，则可以在创建 webhook 时将 `REPOSITORY_NAME` 指定为筛选条件。
1. 如果您要创建组织 webhook，请确保该组织 CodeBuild 有权在其中创建组织级 Webhook。 GitHub您可以创建具有组织 webhook 权限的 GitHub个人访问令牌，也可以使用 CodeBuild OAuth。有关更多信息，请参阅 [GitHub 和 GitHub 企业服务器访问令牌](access-tokens-github.md)。
请注意，组织 webhook 适用于任何现有的 GitHub webhook 事件类型。
1. 如果您要创建全局 webhook，则需要手动创建 webhook。有关如何在其中手动创建 webhook 的更多信息 GitHub，请参阅[GitHub 手动 webhook](github-manual-webhook.md)。
请注意，全局 webhook 仅支持 `WORKFLOW_JOB_QUEUED` 事件类型。有关更多信息，请参阅 [教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。
# 筛选 GitHub 全局或组织 webhook 事件（控制台）
通过控制台创建 GitHub 项目时，请选择以下选项在项目中创建 GitHub 全局或组织 webhook。有关全局和组织 GitHub webhook 的更多信息，请参阅[GitHub 全球和组织 webhook](github-global-organization-webhook.md)。
1. 在 [https://console.aws.amazon.com/codesuite/codebuild](https://console.aws.amazon.com/codesuite/codebuild/home) /home 中打开 AWS CodeBuild 控制台。
1. 创建构建项目。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)和[运行构建（控制台）](run-build-console.md)。
+ 在**源**中：
+ 对于**源提供商**，请选择**GitHub**或**GitHub企业**。
+ 对于**存储库**，选择**GitHub作用域化的 webh** ook。
GitHub 存储库将自动设置为`CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`，这是全局和组织 webhook 所需的源位置。
**注意**
如果您使用的是组织 webhook，请确保 CodeBuild 它有权在其中创建组织级 Webhook。 GitHub如果您使用的是[现有 OAuth连接](oauth-app-github.md)，则可能需要重新生成连接才能授予 CodeBuild 此权限。或者，您可以使用[CodeBuild 手动 webhook 功能手动创建 webhook](github-manual-webhook.md)。请注意，如果您已有 GitHub OAuth 令牌并想添加其他组织权限，则可以通过控制台[撤消该 OAuth 令牌的权限](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps)并重新连接该令牌。 CodeBuild
![\[GitHub 限定作用域的 webhook 的配置。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-organization-webhook-source.png)
+ 在**主要源 Webhook 事件**中：
+ 在**范围类型**中，如果您要创建组织 webhook，请选择**组织级**；如果要创建全局 webhook，请选择**企业级**。
+ 在**名称**中，输入企业或组织名称，具体取决于该 webhook 是全局 webhook 还是组织 webhook。
如果项目的源类型为 `GITHUB_ENTERPRISE`，则还需要在 webhook 组织配置过程中指定一个域。例如，如果您组织的 URL 是 **https://domain.com/orgs/org-name**，则域是 **https://domain.com**。
**注意**
创建 webhook 后不能更改此名称。要更改名称，您可以删除并重新创建 webhook。如果要完全移除 webhook，也可以将项目源位置更新为 GitHub存储库。
![\[全局或组织 webhook 的配置。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-organization-webhook-primary-events.png)
+ （可选）在 **webhook 事件筛选条件组**中，您可以指定[要触发新构建的事件](github-webhook.md)。您也可以指定 `REPOSITORY_NAME` 作为筛选条件，仅根据来自特定存储库的 webhook 事件触发构建。
![\[仅根据来自特定存储库的 webhook 事件触发构建的筛选条件。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-organization-webhook-filter-groups.png)
您也可以将事件类型设置为，`WORKFLOW_JOB_QUEUED`以设置自托管的 Actions GitHub 运行器。有关更多信息，请参阅 [教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。
1. 继续使用默认值，然后选择**创建构建项目**。
# 筛选 GitHub 组织 webhook 事件 ()CloudFormation
要使用 CloudFormation 模板筛选组织 webhook 事件，请使用 AWS CodeBuild 项目的`ScopeConfiguration`属性。有关全局和组织 GitHub webhook 的更多信息，请参阅[GitHub 全球和组织 webhook](github-global-organization-webhook.md)。
**注意**
不支持全局 webhook 和 GitHub 企业 Webhook。 CloudFormation
CloudFormation 模板中以下 YAML 格式的部分创建了四个筛选器组。当这些筛选条件组的其中一个或全部评估为 True 时触发构建：
+ 第一个筛选器组指定`^refs/heads/main$`由没有账户 ID 的 GitHub 用户在具有与正则表达式匹配的 Git 引用名称的分支上创建或更新拉取请求`12345`。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/.*` 匹配的 Git 引用名称，指定在名称与正则表达式 `READ_ME` 匹配的文件上创建的推送请求。
+ 第三个筛选条件组指定一个推送请求，其中包含与正则表达式 `\[CodeBuild\]` 匹配的 HEAD 提交消息。
+ 第四个筛选器组指定 Act GitHub ions 工作流任务请求，其工作流程名称与正则表达式匹配`\[CI-CodeBuild\]`。
```
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: GITHUB
Location: source-location
Triggers:
Webhook: true
ScopeConfiguration:
Name: organization-name
Scope: GITHUB_ORGANIZATION
FilterGroups:
- - Type: EVENT
Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED
- Type: BASE_REF
Pattern: ^refs/heads/main$
ExcludeMatchedPattern: false
- Type: ACTOR_ACCOUNT_ID
Pattern: 12345
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: HEAD_REF
Pattern: ^refs/heads/.*
- Type: FILE_PATH
Pattern: READ_ME
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: COMMIT_MESSAGE
Pattern: \[CodeBuild\]
- Type: FILE_PATH
Pattern: ^src/.+|^test/.+
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
# GitHub 手动 webhook
您可以配置手动 GitHub webhook，以 CodeBuild 防止自动尝试在其中创建 webhook。 GitHub CodeBuild 在创建 webhook 的调用中返回一个有效负载 URL，可用于在其中手动创建 webhook。 GitHub即使未 CodeBuild 被允许在您的 GitHub 账户中创建 webhook，您仍然可以为构建项目手动创建 webhook。
使用以下步骤创建 GitHub 手动 webhook。
**创建手 GitHub 动 webhook**
1. 在 [https://console.aws.amazon.com/codesuite/codebuild](https://console.aws.amazon.com/codesuite/codebuild/home) /home 中打开 AWS CodeBuild 控制台。
1. 创建构建项目。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)和[运行构建（控制台）](run-build-console.md)。
+ 在**源**中：
+ 对于**源提供商**，请选择**GitHub**。
+ 在 “**存储库**” 中，选择 “**我的 GitHub 账户中的存储库**”。
+ 对于**存储库 URL**，输入 **https://github.com/*user-name*/*repository-name***。
+ 在**主要源 Webhook 事件**中：
+ 对于 **webhook - 可选**，选择**每次将代码更改推送到此存储库时都会重新构建**。
+ 选择 “**其他配置**”，选择 “**手动创建”-可选**，**在 GitHub 控制台中为该存储库手动创建 webhook**。 。
1. 继续使用默认值，然后选择**创建构建项目**。请记下**有效载荷 URL** 和**密钥**值，因为稍后要用到它们。
![\[手动 webhook 的有效载荷 URL 和密钥配置。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-manual-webhook-values.png)
1. 打开 GitHub 控制台，`https://github.com/user-name/repository-name/settings/hooks`然后选择**添加 webhook**。
+ 在**有效载荷 URL** 中，输入之前记下的有效载荷 URL 值。
+ 在**内容类型**中，选择 **application/json**。
+ 在**密钥**中，输入之前记下的密钥值。
+ 配置将向其发送 webhook 有效负载的各个事件。 CodeBuild在**您希望哪些事件可触发这个 webhook？**中，选择**让我选择单个事件**，然后从以下事件中选择：**推送**、**拉取请求**和**发布**。如果要为 `WORKFLOW_JOB_QUEUED` 事件启动构建，请选择**工作流作业**。要了解有关 GitHub 操作运行器的更多信息，请参阅[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。要了解有关所支持的事件类型的更多信息 CodeBuild，请参阅[GitHub webhook 事件](github-webhook.md)。
1. 选择**添加 webhook**。
# GitHub webhook 事件
您可以使用 webhook 筛选器组来指定哪些 GitHub Webhook 事件会触发构建。例如，您可以指定仅在对特定分支做出更改时触发构建。
您可以创建一个或多个 Webhook 筛选条件组，来指定哪些 Webhook 事件触发构建。如果任何筛选条件组评估为 true（即组中的所有筛选条件都评估为 true），则会触发构建。创建筛选条件组时，应指定：
**事件**
对于 GitHub，您可以选择以下一个或多个事件：`PUSH`、`PULL_REQUEST_CREATED`、`PULL_REQUEST_UPDATED`、`PULL_REQUEST_REOPENED`、`PULL_REQUEST_MERGED`、`PULL_REQUEST_CLOSED``RELEASED`、`PRERELEASED`、和`WORKFLOW_JOB_QUEUED`。webhook 事件类型在 webhook 负载中的 `X-GitHub-Event` 标头中。在 `X-GitHub-Event` 标头中，您可能会看到 `pull_request` 或 `push`。对于拉取请求事件，类型在 webhook 事件负载的 `action` 字段中。下表显示了 `X-GitHub-Event` 标头值和 webhook 拉取请求负载 `action` 字段值如何映射到可用的事件类型。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/github-webhook.html)
`PULL_REQUEST_REOPENED`事件类型只能与 GitHub和 GitHub 企业服务器一起使用。`RELEASED`和`PRERELEASED`事件类型 GitHub 只能与一起使用。有关 `WORKFLOW_JOB_QUEUED` 的更多信息，请参阅[教程：配置 CodeBuild托管的 GitHub 操作运行器](action-runner.md)。
**一个或多个可选筛选条件**
使用正则表达式来指定筛选条件。对于触发构建的事件，组内与其关联的每个筛选条件都必须评估为 True。
`ACTOR_ACCOUNT_ID`（控制台中的 `ACTOR_ID`）
当 GitHub 或 GitHub企业服务器帐户 ID 与正则表达式模式匹配时，Webhook 事件会触发构建。此值在 webhook 负载中的 `sender` 对象的 `id` 属性中。
`HEAD_REF`
当头部引用与正则表达式模式（例如 `refs/heads/branch-name` 和 `refs/tags/tag-name`）匹配时，Webhook 事件会触发构建。对于推送事件，引用名称在 Webhook 负载中的 `ref` 属性中。对于拉取请求事件，分支名称在 Webhook 负载中的 `head` 对象的 `ref` 属性中。
`BASE_REF`
当基本引用与正则表达式模式（例如 `refs/heads/branch-name`）匹配时，Webhook 事件会触发构建。`BASE_REF` 筛选器只能与拉取请求事件一起使用。分支名称在 webhook 负载中的 `base` 对象的 `ref` 属性中。
`FILE_PATH`
当更改的文件的路径与正则表达式模式匹配时，Webhook 会触发构建。`FILE_PATH`筛选器可用于 GitHub 推送和拉取请求事件以及 GitHub企业服务器推送事件。它不能用于 GitHub企业服务器拉取请求事件。
`COMMIT_MESSAGE`
当 HEAD 提交消息与正则表达式模式匹配时，Webhook 会触发构建操作。`COMMIT_MESSAGE`筛选器可用于 GitHub 推送和拉取请求事件以及 GitHub企业服务器推送事件。它不能用于 GitHub企业服务器拉取请求事件。
`TAG_NAME`
当发布的标签名称与正则表达式模式匹配时，webhook 会触发构建操作。`TAG_NAME`过滤器可用于 GitHub 已发布和预发布的请求事件。
`RELEASE_NAME`
当发布名称与正则表达式模式匹配时，webhook 会触发构建操作。`RELEASE_NAME`过滤器可用于 GitHub 已发布和预发布的请求事件。
`REPOSITORY_NAME`
当存储库名称与正则表达式模式匹配时，webhook 会触发构建操作。`REPOSITORY_NAME`过滤器只能用于 GitHub 全局或组织 webhook。
`ORGANIZATION_NAME`
当组织名称与正则表达式模式匹配时，webhook 会触发构建。`ORGANIZATION_NAME`过滤器只能用于 GitHub 全局 webhook。
`WORKFLOW_NAME`
当工作流名称与正则表达式模式匹配时，Webhook 会触发构建操作。`WORKFLOW_NAME`筛选器可以用于 Acti GitHub ons 工作流程任务队列请求事件。
**注意**
你可以在仓库的 webhook 设置中找到 webhook 有效负载。 GitHub
**Topics**
+ [筛选 GitHub webhook 事件（控制台）](github-webhook-events-console.md)
+ [筛选 GitHub webhook 事件 (SDK)](github-webhook-events-sdk.md)
+ [筛选 GitHub webhook 事件 ()CloudFormation](github-webhook-events-cfn.md)
# 筛选 GitHub webhook 事件（控制台）
按照以下说明使用过滤 GitHub webhook 事件。 AWS 管理控制台有关 GitHub webhook 事件的更多信息，请参阅[GitHub webhook 事件](github-webhook.md)。
在**主要源 webhook 事件**中，选择以下内容。只有当您在**我的 GitHub账户中为源存储库选择存储库**时，此部分才可用。
1. 创建项目时，选择**每次将代码更改推送到此存储库时都会重新构建**。
1. 从**事件类型**中，选择一个或多个事件。
1. 要在事件触发构建时进行筛选，请在**在这些条件下开始构建**下，添加一个或多个可选筛选条件。
1. 要在未触发事件时进行筛选，请在**在这些条件下不开始构建**下，添加一个或多个可选筛选条件。
1. 选择**添加筛选条件组**，以添加另一个筛选条件组（如果需要）。
有关更多信息，请参阅《*AWS CodeBuild API 参考*》中的[创建构建项目（控制台）](create-project.md#create-project-console)和[WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
在此示例中，Webhook 筛选条件组仅针对拉取请求触发构建：
![\[一个 webhook 筛选条件组，仅针对拉取请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter.png)
以两个 Webhook 筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/branch1$` 匹配的头部引用，指定在分支上创建、更新或重新打开的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/branch1$` 匹配的 Git 引用名称，指定分支上的推送请求。
![\[两个筛选条件组的示例。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png)
在此示例中，Webhook 筛选条件组会针对除标记事件之外的所有请求触发构建。
![\[一个 webhook 筛选条件组，针对除标记事件之外的所有请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png)
在此示例中，仅当名称与正则表达式 `^buildspec.*` 匹配的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当文件名称与指定的正则表达式匹配时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)
在此示例中，仅当 `src` 或 `test` 文件夹中的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当指定文件夹中的文件发生更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex.png)
在此示例中，只有当帐户 ID 与正则表达式`actor-account-id`匹配的指定用户 GitHub 或 GitHub 企业服务器用户进行更改时，Webhook 筛选器组才会触发构建。
**注意**
有关如何查找您的 GitHub 账户 ID 的信息，请参阅 https://api.github.com/users/*user-name*，您的 GitHub 用户名在*user-name*哪里。
![\[一个 webhook 过滤器组，只有当账户 ID 与正则表达式匹配的指定 GitHub 用户进行更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png)
在本示例中，当 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，Webhook 筛选条件组会触发推送事件的构建。
![\[一个 webhook 筛选条件组，当 HEAD 提交消息与正则表达式匹配时会触发推送事件的构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)
在此示例中，webhook 筛选器组仅触发 Actions 工作 GitHub 流程作业事件的构建。
**注意**
CodeBuild 仅当 Webhook 具有包含 WORKFLOW\$1JOB **\$1QUEUED 事件过滤器的筛选器组时，才会处理 GitHub 操作工作流作**业。
![\[Webhook 筛选器组仅触发 GitHub 操作工作流程作业事件的构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-actions-workflow-job-queued-no-highlight.png)
在此示例中，当工作流名称与正则表达式 `CI-CodeBuild` 匹配时，webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，当工作流名称与正则表达式匹配时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-actions-workflow-job-specific.png)
# 筛选 GitHub webhook 事件 (SDK)
要使用 AWS CodeBuild SDK 筛选 webhook 事件，请使用`CreateWebhook`或 `UpdateWebhook` API 方法的请求语法中的`filterGroups`字段。有关更多信息，请参阅《CodeBuild API Reference》**中的 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
有关 GitHub webhook 事件的更多信息，请参阅[GitHub webhook 事件](github-webhook.md)。
要创建仅针对拉取请求触发构建的 Webhook 筛选条件，请在请求语法中插入以下内容：
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
}
]
]
```
要创建仅针对指定分支触发构建的 Webhook 筛选条件，请使用 `pattern` 参数指定用于筛选分支名称的正则表达式。以两个筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/myBranch$` 匹配的头部引用，指定在分支上创建、更新或重新打开的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/myBranch$` 匹配的 Git 引用名称，指定分支上的推送请求。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
},
{
"type": "BASE_REF",
"pattern": "^refs/heads/main$"
}
],
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
}
]
]
```
您可以使用 `excludeMatchedPattern` 参数指定不触发构建的事件。例如，在此示例中，将针对除标记事件之外的所有请求触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/tags/.*",
"excludeMatchedPattern": true
}
]
]
```
您可以创建只有当名称与 `pattern` 参数中的正则表达式匹配的文件发生更改时，才触发构建的筛选条件。在此示例中，筛选条件组指定仅当名称与正则表达式 `^buildspec.*` 匹配的文件更改时才触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^buildspec.*"
}
]
]
```
在此示例中，筛选条件组指定仅当 `src` 或 `test` 文件夹中的文件发生更改时，才会触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^src/.+|^test/.+"
}
]
]
```
您可以创建仅当具有帐户 ID 的指定用户 GitHub 或 E GitHub nterprise Server 用户进行更改时才会触发构建的筛选器`actor-account-id`。
**注意**
有关如何查找您的 GitHub 账户 ID 的信息，请参阅 https://api.github.com/users/*user-name*，您的 GitHub 用户名在*user-name*哪里。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED"
},
{
"type": "ACTOR_ACCOUNT_ID",
"pattern": "actor-account-id"
}
]
]
```
您可以创建一个筛选条件，仅当 HEAD 提交消息与模式参数中的正则表达式匹配时才触发构建操作。在本示例中，筛选条件组指定仅当推送事件的 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，才触发构建操作。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "COMMIT_MESSAGE",
"pattern": "\[CodeBuild\]"
}
]
]
```
要创建仅触发 Actions 工作流程任务生成的 GitHub webhook 过滤器，请在请求语法中插入以下内容：
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "WORKFLOW_JOB_QUEUED"
}
]
]
```
# 筛选 GitHub webhook 事件 ()CloudFormation
要使用 CloudFormation 模板过滤 webhook 事件，请使用 AWS CodeBuild 项目的`FilterGroups`属性。
有关 GitHub webhook 事件的更多信息，请参阅[GitHub webhook 事件](github-webhook.md)。
CloudFormation 模板的以下 YAML 格式的部分创建两个筛选条件组。当这两个筛选条件的其中一个或两个评估为 True 时触发构建：
+ 第一个筛选器组指定`^refs/heads/main$`由没有账户 ID 的 GitHub 用户在具有与正则表达式匹配的 Git 引用名称的分支上创建或更新拉取请求`12345`。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/.*` 匹配的 Git 引用名称，指定在名称与正则表达式 `READ_ME` 匹配的文件上创建的推送请求。
+ 第三个筛选条件组指定一个推送请求，其中包含与正则表达式 `\[CodeBuild\]` 匹配的 HEAD 提交消息。
+ 第四个筛选器组指定 Act GitHub ions 工作流任务请求，其工作流程名称与正则表达式匹配`\[CI-CodeBuild\]`。
```
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: GITHUB
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
- Type: ACTOR_ACCOUNT_ID
Pattern: 12345
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: HEAD_REF
Pattern: ^refs/heads/.*
- Type: FILE_PATH
Pattern: READ_ME
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: COMMIT_MESSAGE
Pattern: \[CodeBuild\]
- Type: FILE_PATH
Pattern: ^src/.+|^test/.+
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
# GitLab 群组 webhook
您可以使用 CodeBuild GitLab 群组 webhook 在群组内任何存储库的 webhook 事件上启动构建。 GitLab 群组 webhook 可与任何现有的 GitLab webhook 事件类型配合使用，并且可以通过在创建 webhook 时添加范围配置来进行配置。 CodeBuild 您还可以使用群组 webhook 在[其中设置自托管的 GitLab运行器，以便 CodeBuild在单个项目中](gitlab-runner.md)接收来自多个存储库`WORKFLOW_JOB_QUEUED`的事件。
**Topics**
+ [设置群组 GitLab webhook](gitlab-group-webhook-setup.md)
+ [筛选 GitLab 群组 webhook 事件（控制台）](gitlab-group-webhook-events-console.md)
+ [筛选 GitLab 群组 webhook 事件 ()CloudFormation](gitlab-group-webhook-events-cfn.md)
# 设置群组 GitLab webhook
设置群组 GitLab webhook 的高级步骤如下。有关群组 GitLab webhook 的更多信息，请参阅[GitLab 群组 webhook](gitlab-group-webhook.md)。
1. 将项目的源位置设置为 `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`。
1. 在 webhook 的范围配置中，将范围设置为 `GITLAB_GROUP`。
1. 在 webhook 的范围配置过程中指定一个名称。对于组 webhook，这是组名称。
**注意**
如果项目的源类型为 `GITLAB_SELF_MANAGED`，则还需要在 webhook 范围配置过程中指定一个域。
1. （可选）如果您只想接收组织或企业内特定存储库的 webhook 事件，则可以在创建 webhook 时将 `REPOSITORY_NAME` 指定为筛选条件。
1. 创建群组 webhook 时，请确保该群组 CodeBuild 有权在群组内创建群组级 Webhook。 GitLab CodeBuild OAuth 但要做到这一点，你可以使用 CodeConnections。有关更多信息，请参阅 [GitLab 进入 CodeBuild](access-tokens-gitlab-overview.md)。
请注意，群组 webhook 适用于任何现有的 GitLab webhook 事件类型。
# 筛选 GitLab 群组 webhook 事件（控制台）
通过控制台创建 GitLab 项目时，请选择以下选项在项目中创建 GitLab 群组 webhook。有关群组 GitLab webhook 的更多信息，请参阅[GitLab 群组 webhook](gitlab-group-webhook.md)。
1. 在 [https://console.aws.amazon.com/codesuite/codebuild](https://console.aws.amazon.com/codesuite/codebuild/home) /home 中打开 AWS CodeBuild 控制台。
1. 创建构建项目。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)和[运行构建（控制台）](run-build-console.md)。
+ 在**源**中：
+ 对于**源提供商**，请选择**GitLab**或**GitLab自行管理**。
+ 对于 “**存储库**”，选择 **GitLabscoped webhoo** k。
GitLab 存储库将自动设置为`CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`，这是群组 webhook 所需的源位置。
**注意**
使用群组 webhook 时，请确保该群组 CodeBuild 有权在群组内创建群组级 webhook。 GitLab如果您使用的是[现有 OAuth连接](access-tokens-gitlab-overview.md#connections-gitlab)，则可能需要重新生成连接才能授予 CodeBuild 此权限。
![\[GitLab 限定作用域的 webhook 的配置。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/gitlab-group-source.png)
+ 在**主要源 Webhook 事件**中：
+ 在**组名称**中，输入组名称。
如果项目的源类型为 `GITLAB_SELF_MANAGED`，则还需要在 webhook 组配置过程中指定一个域。例如，如果组的 URL 是 **https://domain.com/group/group-name**，则域是 **https://domain.com**。
**注意**
创建 webhook 后不能更改此名称。要更改名称，您可以删除并重新创建 webhook。如果要完全移除 webhook，也可以将项目源位置更新为 GitLab存储库。
![\[组 webhook 的配置。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/gitlab-group-webhook-primary-events.png)
+ （可选）在 **webhook 事件筛选条件组**中，您可以指定[要触发新构建的事件](gitlab-webhook.md)。您也可以指定 `REPOSITORY_NAME` 作为筛选条件，仅根据来自特定存储库的 webhook 事件触发构建。
![\[仅根据来自特定存储库的 webhook 事件触发构建的筛选条件。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/github-organization-webhook-filter-groups.png)
您也可以将事件类型设置为`WORKFLOW_JOB_QUEUED`以设置自托管的 GitLab 运行器。有关更多信息，请参阅 [自我管理的 GitLab 跑步者在 AWS CodeBuild](gitlab-runner.md)。
1. 继续使用默认值，然后选择**创建构建项目**。
# 筛选 GitLab 群组 webhook 事件 ()CloudFormation
要使用 CloudFormation 模板来筛选群组 webhook 事件，请使用 AWS CodeBuild 项目的`ScopeConfiguration`属性。有关群组 GitLab webhook 的更多信息，请参阅[GitLab 群组 webhook](gitlab-group-webhook.md)。
CloudFormation 模板中以下 YAML 格式的部分创建了四个筛选器组。当这些筛选条件组的其中一个或全部评估为 True 时触发构建：
+ 第一个筛选器组指定`^refs/heads/main$`由没有账户 ID 的 GitLab 用户在具有与正则表达式匹配的 Git 引用名称的分支上创建或更新拉取请求`12345`。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/.*` 匹配的 Git 引用名称，指定在名称与正则表达式 `READ_ME` 匹配的文件上创建的推送请求。
+ 第三个筛选条件组指定一个推送请求，其中包含与正则表达式 `\[CodeBuild\]` 匹配的 HEAD 提交消息。
+ 第四个筛选器组指定与正则表达式相匹配的 GitLab CI/CD pipeline job request with a CI/CD管道名称`\[CI-CodeBuild\]`。
```
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: GITLAB
Location: source-location
Triggers:
Webhook: true
ScopeConfiguration:
Name: group-name
Scope: GITLAB_GROUP
FilterGroups:
- - Type: EVENT
Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED
- Type: BASE_REF
Pattern: ^refs/heads/main$
ExcludeMatchedPattern: false
- Type: ACTOR_ACCOUNT_ID
Pattern: 12345
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: HEAD_REF
Pattern: ^refs/heads/.*
- Type: FILE_PATH
Pattern: READ_ME
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: COMMIT_MESSAGE
Pattern: \[CodeBuild\]
- Type: FILE_PATH
Pattern: ^src/.+|^test/.+
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
# GitLab 手动 webhook
您可以配置手动 GitLab webhook，以防止 CodeBuild 自动尝试在 GitLab 中创建 webhook。CodeBuild 在创建 webhook 的调用过程中返回有效载荷 URL，并可用于在 GitLab 中手动创建 webhook。即使 CodeBuild 未列入允许列表而无法在 GitLab 账户中创建 webhook，您仍然可为您的构建项目手动创建 webhook。
使用以下过程创建 GitLab 手动 webhook。
**创建 GitLab 手动 webhook**
1. 从 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 打开 AWS CodeBuild 控制台。
1. 创建构建项目。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)和[运行构建（控制台）](run-build-console.md)。
+ 在**源**中：
+ 对于**源提供商**，选择 **GitLab**。
+ 对于**存储库**，选择**我的 GitLab 账户中的存储库**。
+ 对于**存储库 URL**，输入 **https://gitlab.com/*user-name*/*repository-name***。
+ 在**主要源 Webhook 事件**中：
+ 对于 **webhook - 可选**，选择**每次将代码更改推送到此存储库时都会重新构建**。
+ 选择**其他配置**，然后对于**手动创建 - 可选**，选择**在 GitLab 控制台中为此存储库手动创建 webhook**。
1. 继续使用默认值，然后选择**创建构建项目**。请记下**有效载荷 URL** 和**密钥**值，因为稍后要用到它们。
1. 在 `https://gitlab.com/user-name/repository-name/-/hooks` 中打开 GitLab 控制台，然后选择**添加新的 webhook**。
+ 对于 **URL**，输入之前记下的有效载荷 URL 值。
+ 在**密钥令牌**中，输入之前记下的密钥值。
+ 配置将向 CodeBuild 发送 webhook 有效载荷的各个事件。对于**触发器**，请从以下事件中进行选择：**推送事件**、**合并请求事件**、**发布事件**和**作业事件**。要了解有关 CodeBuild 支持的事件类型的更多信息，请参阅[GitLab webhook 事件](gitlab-webhook.md)。
1. 选择**添加 webhook**。
# GitLab webhook 事件
您可以使用 webhook 筛选器组来指定哪些 GitLab Webhook 事件会触发构建。例如，您可以指定仅在对特定分支做出更改时触发构建。
您可以创建一个或多个 Webhook 筛选条件组，来指定哪些 Webhook 事件触发构建。如果任何筛选条件组评估为 true（即组中的所有筛选条件都评估为 true），则会触发构建。创建筛选条件组时，应指定：
**事件**
对于 GitLab，您可以选择以下一个或多个事件：`PUSH`、`PULL_REQUEST_CREATED`、`PULL_REQUEST_UPDATED`、`PULL_REQUEST_MERGED`、`PULL_REQUEST_REOPENED``PULL_REQUEST_CLOSED`、`RELEASED`、和`WORKFLOW_JOB_QUEUED`。
webhook 的事件类型位于其在 `X-GitLab-Event` 字段中的标头中。下表显示了 `X-GitLab-Event` 标头值如何映射到事件类型。对于 `Merge Request Hook` webhook 事件，有效载荷的 `object_atttributes.action` 将包含有关合并请求类型的更多信息。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/gitlab-webhook.html)
对于 `PULL_REQUEST_MERGED`，如果拉取请求与压缩策略合并且拉取请求分支已关闭，则原始的拉取请求提交将不再存在。在这种情况下，`CODEBUILD_WEBHOOK_MERGE_COMMIT` 环境变量包含压缩后的合并提交的标识符。
**一个或多个可选筛选条件**
使用正则表达式来指定筛选条件。对于触发构建的事件，组内与其关联的每个筛选条件都必须评估为 True。
`ACTOR_ACCOUNT_ID`（控制台中的 `ACTOR_ID`）
当 GitLab 账户 ID 与正则表达式模式匹配时，Webhook 事件会触发构建。此值显示在 Webhook 筛选条件负载中的 `actor` 对象的 `account_id` 属性中。
`HEAD_REF`
当头部引用与正则表达式模式（例如 `refs/heads/branch-name` 和 `refs/tags/tag-name`）匹配时，Webhook 事件会触发构建。`HEAD_REF` 筛选条件将评估分支或标签的 Git 引用名称。分支或标签名称显示在 Webhook 负载的 `push` 对象中的 `new` 对象的 `name` 字段中。对于拉取请求事件，分支名称显示在 Webhook 负载中的 `source` 对象的 `branch` 中的 `name` 字段中。
`BASE_REF`
当基础引用与正则表达式模式匹配时，Webhook 事件会触发构建。`BASE_REF` 筛选条件仅处理拉取请求事件（例如，`refs/heads/branch-name`）。`BASE_REF` 筛选条件评估分支的 Git 引用名称。分支名称显示在 `branch` 对象的 `name` 字段中，该对象位于 Webhook 负载的 `destination` 对象中。
`FILE_PATH`
当更改的文件的路径与正则表达式模式匹配时，Webhook 会触发构建。
`COMMIT_MESSAGE`
当 HEAD 提交消息与正则表达式模式匹配时，Webhook 会触发构建操作。
`WORKFLOW_NAME`
当工作流名称与正则表达式模式匹配时，Webhook 会触发构建操作。
**注意**
你可以在仓库的 webhook 设置中找到 webhook 有效负载。 GitLab
**Topics**
+ [筛选 GitLab webhook 事件（控制台）](gitlab-webhook-events-console.md)
+ [筛选 GitLab webhook 事件 (SDK)](gitlab-webhook-events-sdk.md)
+ [筛选 GitLab webhook 事件 ()CloudFormation](gitlab-webhook-events-cfn.md)
# 筛选 GitLab webhook 事件（控制台）
按照以下说明使用过滤 webhook 事件。 AWS 管理控制台 有关 GitLab webhook 事件的更多信息，请参阅[GitLab webhook 事件](gitlab-webhook.md)。
1. 创建项目时，选择**每次将代码更改推送到此存储库时都会重新构建**。
1. 从**事件类型**中，选择一个或多个事件。
1. 要在事件触发构建时进行筛选，请在**在这些条件下开始构建**下，添加一个或多个可选筛选条件。
1. 要在未触发事件时进行筛选，请在**在这些条件下不开始构建**下，添加一个或多个可选筛选条件。
1. 选择**添加筛选条件组**以添加另一个筛选条件组。
有关更多信息，请参阅《*AWS CodeBuild API 参考*》中的[创建构建项目（控制台）](create-project.md#create-project-console)和[WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
在此示例中，Webhook 筛选条件组仅针对拉取请求触发构建：
![\[一个 webhook 筛选条件组，仅针对拉取请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-gitlab.png)
以两个筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/branch1!` 匹配的 HEAD 引用，指定在分支上创建或更新的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/branch1$` 匹配的 Git 引用名称，指定分支上的推送请求。
![\[两个筛选条件组的示例。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-gitlab.png)
在此示例中，Webhook 筛选条件组会针对除标记事件之外的所有请求触发构建。
![\[一个 webhook 筛选条件组，针对除标记事件之外的所有请求触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-gitlab.png)
在此示例中，仅当名称与正则表达式 `^buildspec.*` 匹配的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当文件名称与指定的正则表达式匹配时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex-gitlab.png)
在此示例中，仅当 `src` 或 `test` 文件夹中的文件发生更改时，Webhook 筛选条件组才会触发构建。
![\[一个 webhook 筛选条件组，仅当指定文件夹中的文件发生更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex-gitlab.png)
在此示例中，只有当账户 ID 与正则表达式`actor-account-id`不匹配的 GitLab 用户进行更改时，Webhook 筛选器组才会触发构建。
**注意**
有关如何查找您的 GitLab 账户 ID 的信息，请参阅 https://api.github.com/users/*user-name*，您的 GitLab 用户名在*user-name*哪里。
![\[一个 webhook 筛选器组，只有在没有账户 ID 的 GitLab 用户进行更改时才会触发构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-gitlab.png)
在本示例中，当 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，Webhook 筛选条件组会触发推送事件的构建。
![\[一个 webhook 筛选条件组，当 HEAD 提交消息与正则表达式匹配时会触发推送事件的构建。\]](http://docs.aws.amazon.com/zh_cn/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message-gitlab.png)
# 筛选 GitLab webhook 事件 (SDK)
要使用 AWS CodeBuild SDK 筛选 webhook 事件，请使用`CreateWebhook`或 `UpdateWebhook` API 方法的请求语法中的`filterGroups`字段。有关更多信息，请参阅《CodeBuild API Reference》**中的 [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html)。
有关 GitLab webhook 事件的更多信息，请参阅[GitLab webhook 事件](gitlab-webhook.md)。
要创建仅针对拉取请求触发构建的 Webhook 筛选条件，请在请求语法中插入以下内容：
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED"
}
]
]
```
要创建仅针对指定分支触发构建的 Webhook 筛选条件，请使用 `pattern` 参数指定用于筛选分支名称的正则表达式。以两个筛选条件组为例，当一个或两个筛选条件评估为 True 时触发构建：
+ 第一个筛选条件组使用与正则表达式 `^refs/heads/main$` 匹配的 Git 引用名称以及与 `^refs/heads/myBranch$` 匹配的 HEAD 引用，指定在分支上创建或更新的拉取请求。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/myBranch$` 匹配的 Git 引用名称，指定分支上的推送请求。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
},
{
"type": "BASE_REF",
"pattern": "^refs/heads/main$"
}
],
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "HEAD_REF",
"pattern": "^refs/heads/myBranch$"
}
]
]
```
您可以使用 `excludeMatchedPattern` 参数指定不触发构建的事件。在此示例中，将针对除标记事件之外的所有请求触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED"
},
{
"type": "HEAD_REF",
"pattern": "^refs/tags/.*",
"excludeMatchedPattern": true
}
]
]
```
您可以创建一个过滤器，该过滤器仅在具有账户 ID 的 GitLab用户进行更改时才会触发构建`actor-account-id`。
**注意**
有关如何查找您的 GitLab 账户 ID 的信息，请参阅 https://api.github.com/users/*user-name*，您的 GitLab 用户名在*user-name*哪里。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED"
},
{
"type": "ACTOR_ACCOUNT_ID",
"pattern": "actor-account-id"
}
]
]
```
您可以创建只有当名称与 `pattern` 参数中的正则表达式匹配的文件发生更改时，才触发构建的筛选条件。在此示例中，筛选条件组指定仅当名称与正则表达式 `^buildspec.*` 匹配的文件更改时才触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^buildspec.*"
}
]
]
```
在此示例中，筛选条件组指定仅当 `src` 或 `test` 文件夹中的文件发生更改时，才会触发构建。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "FILE_PATH",
"pattern": "^src/.+|^test/.+"
}
]
]
```
您可以创建一个筛选条件，仅当 HEAD 提交消息与模式参数中的正则表达式匹配时才触发构建操作。在本示例中，筛选条件组指定仅当推送事件的 HEAD 提交消息与正则表达式 `\[CodeBuild\]` 匹配时，才触发构建操作。
```
"filterGroups": [
[
{
"type": "EVENT",
"pattern": "PUSH"
},
{
"type": "COMMIT_MESSAGE",
"pattern": "\[CodeBuild\]"
}
]
]
```
# 筛选 GitLab webhook 事件 ()CloudFormation
要使用 CloudFormation 模板过滤 webhook 事件，请使用 AWS CodeBuild 项目的`FilterGroups`属性。有关 GitLab webhook 事件的更多信息，请参阅[GitLab webhook 事件](gitlab-webhook.md)。
CloudFormation 模板的以下 YAML 格式的部分创建两个筛选条件组。当这两个筛选条件的其中一个或两个评估为 True 时触发构建：
+ 第一个筛选器组指定`^refs/heads/main$`由没有账户 ID 的 GitLab 用户在具有与正则表达式匹配的 Git 引用名称的分支上创建或更新拉取请求`12345`。
+ 第二个筛选条件组使用与正则表达式 `^refs/heads/.*` 匹配的 Git 引用名称，指定在分支上创建的推送请求。
+ 第三个筛选条件组指定一个推送请求，其中包含与正则表达式 `\[CodeBuild\]` 匹配的 HEAD 提交消息。
+ 第四个筛选器组指定 Act GitHub ions 工作流任务请求，其工作流程名称与正则表达式匹配`\[CI-CodeBuild\]`。
```
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: GITLAB
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
- Type: ACTOR_ACCOUNT_ID
Pattern: 12345
ExcludeMatchedPattern: true
- - Type: EVENT
Pattern: PUSH
- Type: HEAD_REF
Pattern: ^refs/heads/.*
- - Type: EVENT
Pattern: PUSH
- Type: COMMIT_MESSAGE
Pattern: \[CodeBuild\]
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
# Buildkite 手动 webhook
目前，CodeBuild 要求所有 Buildkite webhook 都需要手动创建。CodeBuild 在创建 webhook 的调用过程中返回有效载荷 URL，可用于在 Buildkite 中手动创建 webhook。
使用以下过程创建 Buildkite 手动 webhook。
**创建带有 webhook 的 CodeBuild 项目**
1. 从 [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 打开 AWS CodeBuild 控制台。
1. 创建构建项目。有关信息，请参阅[创建构建项目（控制台）](create-project.md#create-project-console)和[运行构建（控制台）](run-build-console.md)。
1. 在**项目配置**中，选择**运行程序项目**。
在**运行程序**中：
+ 对于**运行程序提供商**，选择 **Buildkite**。
+ 对于 **Buildkite 代理令牌**，选择**使用创建密钥页面创建新的代理令牌**。系统将提示您在 AWS Secrets Manager 中创建一个新密钥，密钥值等于您在上面生成的 Buildkite 代理令牌。
+ （可选）如果您想在作业中使用 CodeBuild 托管式凭证，请在 **Buildkite 源凭证选项**下选择作业的源存储库提供商，并验证是否已为您的账户配置了凭证。此外，请验证 Buildkite 管道是否采用**使用 HTTPS 签出**。
1.
+ 在**环境**中：
+ 选择支持的**环境映像**和**计算**。请注意，您可以选择在 GitHub Actions 工作流 YAML 中使用标签来覆盖映像和实例设置。有关更多信息，请参阅 [第 2 步：更新您的 GitHub 操作工作流程 YAML](action-runner.md#sample-github-action-runners-update-yaml)。
+ 在 **Buildspec (构建规范)** 中：
+ 请注意，除非将 `buildspec-override:true` 作为标签添加，否则系统会忽略 buildspec。相反，CodeBuild 将覆盖它，以便使用特定命令来设置自托管运行器。
1. 继续使用默认值，然后选择**创建构建项目**。
1. 保存**创建 webhook** 弹出窗口中的**有效载荷 URL** 和**密钥**值。按照弹出窗口中的说明创建新的 Buildkite 组织 webhook。
# 拉取请求评论批准
CodeBuild 支持拉取请求构建策略，这些策略可对由拉取请求触发的构建提供额外的控制。您可能不想自动构建来自未知用户的拉取请求，直到可以审查其更改。此功能可让您要求一名团队成员先审查代码，然后运行管道。这通常用作在构建未知贡献者提交的代码时的安全措施。
拉取请求构建策略允许您根据贡献者的权限和批准状态控制何时为拉取请求生成 CodeBuild 触发器。这对于公共存储库或接受外部协作者贡献的存储库尤为重要。
启用后，此功能可确保只有在以下任一情况下，才会为拉取请求触发构建：
+ 拉取请求由可信贡献者创建。
+ 可信贡献者通过发布特定评论来批准拉取请求。
## 工作原理
**可信贡献者**
可信贡献者是指源代码控制系统中的当前角色在基于拉取请求的策略中设置为批准者角色的用户。当受信任的贡献者创建拉取请求时，会自动 CodeBuild 触发构建，保持当前行为。
**不可信贡献者**
不可信贡献者是指其角色未在批准者角色列表中设置的用户。当不可信贡献者创建拉取请求时：
1. CodeBuild 将构建状态标记为 “失败”，并显示消息 “启动构建需要拉取请求批准”。
1. 可信贡献者必须审核更改并使用 `/codebuild_run()` 发布评论才能触发构建。例如 `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)`。
1. CodeBuild 验证评论者的权限，并在获得批准后触发构建。
1. 构建结果将在拉取请求页面上报告。
**评论批准语法**
可信贡献者可以使用以下评论格式批准构建：
+ `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)`：基于指定的提交 SHA 触发构建。
## 配置
**默认 行为**
默认情况下，所有新创建的 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"]`
## 示例
**为所有拉取请求启用评论批准**
要使用 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
要使用 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
```
## 控制台配置
要使用 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)