自动执行构建以响应网络钩子事件

通过 Cloud Build，您可以定义 Webhook 触发器，这些触发器可以对传入的 Webhook 事件进行身份验证并接受这些事件。将这些事件发送到自定义网址后，您可以通过 Webhook 事件将外部系统和外部源代码管理系统（如 Bitbucket.com、Bitbucket Server 或 GitLab）直接连接到 Cloud Build。

使用 Webhook 触发器，您可以在创建触发器时定义内嵌构建配置文件，而不是指定源代码。通过内嵌构建配置，您可以控制 git 操作并定义构建的其余部分。

本页面概述了如何创建网络钩子触发器，以便自动执行构建以响应网络钩子事件。

准备工作

启用 Cloud Build and Secret Manager API。
启用 API

如需使用此页面上的 gcloud 命令，请安装 Google Cloud CLI。

注意：如果您之前安装了 gcloud CLI，请运行 gcloud components update 以确保您拥有最新的可用版本。

创建 webhook 触发器

控制台

如需使用 Google Cloud 控制台创建 webhook 触发器，请执行以下操作：

打开触发器页面

打开“构建触发器”页面
从页面顶部选择您的项目，然后点击打开。
点击创建触发器。
输入以下触发器设置：
- 名称：触发器的名称。
- 区域：为触发器选择区域。
  - 如果与触发器关联的构建配置文件指定了专用池，则 Cloud Build 会使用专用池来运行构建。在这种情况下，您在触发器中指定的区域必须与创建专用池的区域一致。
  - 如果与触发器关联的构建配置文件未指定专用池，则 Cloud Build 会使用默认池在触发器所在的区域中运行构建。
- 说明（可选）：触发器的说明。
- 事件：选择 Webhook 事件以设置触发器启动构建来响应传入的 Webhook 事件。
- Webhook 网址：使用 Webhook 网址对传入的 Webhook 事件进行身份验证。
  - Secret：您需要使用 Secret 对传入的 Webhook 事件进行身份验证。您可以创建新 Secret，也可以使用现有 Secret。此密钥独立于与您的 SSH 密钥关联的密钥。
    
    如需创建新的 Secret，请执行以下操作：
    1. 选择使用新密钥（由 Cloud Build 生成）。
    2. 点击创建密文。
      
      您将看到创建 Webhook Secret 弹出框。
    3. 在 Secret 名称字段中，输入 Secret 名称。
    4. 点击创建 Secret 以保存您的 Secret，系统将自动在 Secret Manager 中创建并存储该 Secret。
    如需使用现有 Secret，请执行以下操作：
    1. 选择使用现有的密钥或创建自己的密钥。
    2. 在 Secret 字段中，从下拉菜单选择要使用的 Secret 的名称，或者按照说明通过资源 ID 添加 Secret。
    3. 在 Secret 版本字段中，从下拉菜单选择您的 Secret 版本。
    如果您使用现有 Secret，则可能需要手动向您的 Cloud Build 服务账号 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com 授予 Secret Manager Secret Accessor 角色。如需了解详情，请参阅向您的服务账号授予 Secret Manager 角色。
  创建或选择密钥后，您将看到 Webhook 网址预览。您的网址将包含由 Cloud Build 生成的 API 密钥和您的密钥。如果 Cloud Build 无法检索 API 密钥，您可以手动将 API 密钥添加到网址，或者了解如何获取 API 密钥（如果没有）。
  
  借助网址，您可以使用 POST 方法发出 HTTP 请求来调用 Webhook 事件。
  
  使用以下命令调用 webhook 事件：
```
curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"
```
  完成这些步骤后，系统将自动向您的 Cloud Build 服务账号 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com 授予 Secret Manager Secret Accessor 角色。如果您未看到此角色自动添加到您的服务账号，请完成向您的服务账号授予 Secret Manager 角色中所述的步骤。
- Source（可选）：选择要在 webhook 触发器运行时构建的来源。如果您指定内嵌 build 配置，则无需指定以下源代码。您可以指定第 1 代或第 2 代作为来源。如需了解详情，请参阅 Cloud Build 代码库。
  
  注意：您的代码库区域必须与触发器的区域一致。
  - 代码库：从可用代码库列表中，选择所需的代码库。
  - 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。
  - 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：
    
    警告：对代码库拥有读取权限的任何用户都可以提交拉取请求，这可能会执行包含拉取请求中的源代码更改的构建。如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。如需详细了解触发器的构建时权限，请参阅构建触发器和 Cloud Build 服务账号。
    - 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。
    - 必需：当任何贡献者创建或更新拉取请求时，只有在所有者或协作者对拉取请求添加注释 /gcbrun 后，系统才会执行构建。每次对拉取请求进行更改时，都会执行构建。
    - 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。
- 配置：选择位于远程代码库中的构建配置文件，或创建要用于构建的内嵌构建配置文件。如果您未指定源代码库，则必须选择内嵌构建配置文件作为配置选项。
  - 类型：选择要用于构建的配置类型。
    - Cloud Build 配置文件（yaml 或 json）：为您的配置使用构建配置文件。
    - Dockerfile：为您的配置使用 Dockerfile。
    - Buildpack：为您的配置使用 buildpack。
  - 位置：为您的配置指定位置。
    - 代码库：如果您的配置文件位于远程代码库中，请提供构建配置文件、Dockerfile 目录或 buildpack 目录的位置。如果您的构建配置类型是 Dockerfile 或 buildpack，则需要为生成的映像提供名称，还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后，您会看到您的构建将执行的 docker build 或 pack 命令的预览。
    - Buildpack 环境变量（可选）：如果您选择了 buildpacks 作为配置类型，请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量，请参阅环境变量。
    - 内嵌：如果您选择了 Cloud Build 配置文件（yaml 或 json）作为配置选项，则可以指定内嵌构建配置。点击打开编辑器，使用 YAML 或 JSON 语法在 Google Cloud 控制台中编写构建配置文件。点击完成以保存您的构建配置。
      
      注意：内嵌构建配置支持不适用于 Dockerfile 或 buildpack。
  在以下示例中，内嵌构建配置文件记录了回显“hello world”：
```
 steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']
```
- 替代变量（可选）：如果您选择了构建配置文件作为构建配置选项或创建了内嵌构建配置文件，则可以使用此字段选择定义特定于触发器的替代变量。您还可以在定义替代变量值时使用载荷绑定来获取数据。
- 过滤条件（可选）：您可以在触发器中创建一项规则，用于确定触发器是否会根据替代变量执行构建。
点击创建以创建构建触发器。

gcloud

（可选）获取 API 密钥

如需对传入的网络钩子事件进行身份验证，您需要一个 API 密钥。

要获取 API 密钥，请执行以下操作：

打开 Google Cloud 控制台中的凭据页面：

打开“凭据”页面
点击创建凭据。
点击 API 密钥。

您会看到一个对话框，其中含有已创建的 API 密钥。记下您的 API 密钥。
如果您要对产品应用的密钥进行限制，请点击限制密钥，以完成保护密钥的其他步骤。否则，请点击关闭。

如需了解如何限制密钥，请参阅应用 API 密钥限制。

（可选）向您的服务账号授予 Secret Manager 角色

Cloud Build 会自动向在 Secret 配置过程中需要 Secret Manager Secret Accessor 角色的服务账号授予该角色。如果您没有看到此角色自动授予所需的服务账号，请完成以下步骤来手动添加此角色，以便您的服务账号有权访问您的 Secret：

在 Google Cloud 控制台中打开 IAM 页面：

打开 IAM 页面
记下您要向其授予该角色的 Cloud Build 服务账号。
在 Google Cloud 控制台中打开 Secret Manager 页面：

打开 Secret Manager 页面
点击您的 Secret 名称。

您会看到 Secret 详情页面。
1. 点击权限标签页。
2. 点击授予访问权限。
  
  您将看到授予访问权限面板。
3. 在添加主帐号部分中，添加与您的 Cloud Build 服务帐号关联的电子邮件地址。
4. 在分配角色部分中，依次选择 Secret Manager > Secret Manager Secret Accessor。
5. 点击保存。

后续步骤

了解如何创建和管理触发器。
了解如何构建 Bitbucket Server 上托管的代码库。
了解如何手动启动构建。
了解如何查看构建结果。
了解如何排查构建错误。