自动构建以响应 webhook 事件

第 1 代 第 2 代

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

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

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

注意 ：如果您要创建自动基于代码库事件构建的触发器， 建议您使用 Cloud Build 代码库触发器仓库 你可以配置使用 Cloud Build 代码库（第 2 代）的触发器 与源代码提供程序原生集成， 支持 GitHub 和 GitLab。Cloud Build 代码库（第 2 代）还会使用 Secret Manager 代表您管理身份验证令牌和信息。代码库触发器可让您轻松过滤传入事件和构建后 将状态传回来源提供程序，并且也可以配置为 连接网络。如需了解详情， 请参阅代码库概览页面。

准备工作

• Enable the Cloud Build and Secret Manager APIs.

  Enable the APIs

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

  注意 ：如果您之前安装了 gcloud CLI，请确保您拥有 gcloud components update.

创建 webhook 触发器

控制台

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

1. 打开触发器页面

   打开“构建触发器”页面

2. 从页面顶部选择您的项目，然后点击打开。

3. 点击创建触发器。

4. 输入以下触发器设置：

   • 名称：触发器的名称。

   • 区域：为触发器选择区域。

     • 如果与触发器关联的构建配置文件 指定专用池时，Cloud Build 会使用专用池 运行 build。在这种情况下，您在触发器中指定的区域必须与您创建专用池的区域一致。
     • 如果与触发器关联的构建配置文件 不指定专用池； Cloud Build 使用 池，以在同一区域运行构建 作为触发器。

   • 说明（可选）：触发器的说明。

   • 事件：选择 Webhook 事件以设置触发器启动构建来响应传入的 Webhook 事件。

   • Webhook 网址：使用 Webhook 网址对传入的 Webhook 事件进行身份验证。

     • Secret：您需要使用 Secret 对传入的网络钩子事件进行身份验证。您可以创建新密钥或使用现有密钥。这个 Secret 与 SSH 密钥关联的 Secret 是分开的。

       如需创建新的 Secret，请执行以下操作：

       1. 选择使用新密钥（由 Cloud Build 生成）。

       2. 点击创建 Secret。

          您将看到创建 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 "{}"
     

     完成上述步骤后，Secret Manager Secret Accessor 角色将自动授予您的 Cloud Build 服务代理 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com。 如果您没有看到此角色 自动添加到服务代理，请完成以下 授予 Secret Manager 角色中介绍的步骤 您的服务账号。

   • Source（可选）：选择在 webhook 触发 webhook 时要构建的来源 。如果您正在指定内嵌 build 配置，则无需指定以下源代码。您可以将第 1 代或第 2 代指定为来源。如需了解详情，请参阅 Cloud Build 代码库。

     注意 ：代码库的区域必须与 触发器的区域。

     • 代码库：从可用代码库列表中，选择 所需的代码库

     • 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。

     • 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：

       警告 ：对代码库拥有读取权限的任何用户都可以提交拉取请求，这可能会执行包含源代码更改的构建 添加代码如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。您还可以详细了解触发器的构建时权限。

       • 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。

       • 必需：当 那么只有在成为所有者或成员之后， 协作者评论拉取请求 /gcbrun。build 都会在系统每次更改拉取请求时执行。

       • 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。

   • 配置：选择位于远程代码库中的构建配置文件，或创建要用于构建的内嵌构建配置文件。 如果您未指定源代码库，则必须选择内嵌构建配置文件作为配置选项。

     • 类型：选择要用于构建的配置类型。
       • Cloud Build 配置文件（yaml 或 json）：为您的配置使用构建配置文件。
       • Dockerfile：为您的配置使用 Dockerfile。
       • Buildpack：为您的配置使用 buildpack。

     • 位置：为您的配置指定位置。

       • 代码库：如果您的配置文件位于 远程代码库时，请提供您的 构建配置文件，即 Dockerfile 目录或 buildpacks 目录如果您的构建配置类型是 Dockerfile 或 buildpack，则需要为生成的映像提供名称，还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后，您会看到您的构建将执行的 docker build 或 pack 命令的预览。
       • Buildpack 环境变量（可选）：如果您选择了 buildpacks 作为配置类型，请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量，请参阅环境变量。

       • 内嵌：如果您选择了 Cloud Build 配置文件（yaml 或 json）作为配置选项，则可以指定内嵌构建配置。点击 Open Editor（打开编辑器），在 使用 YAML 或 JSON 语法创建 Google Cloud 控制台。点击完成以保存您的构建配置。

         注意：内嵌构建配置支持不适用于 Dockerfile 或 buildpack。

     在以下示例中，内嵌构建配置文件记录了回显“hello world”：

      steps:
      - name: 'ubuntu'
        args: ['echo', 'hello world']
     

   • 替代变量（可选）：如果您选择了构建配置文件作为构建配置选项或创建了内嵌构建配置文件，则可以使用此字段选择定义特定于触发器的替代变量。您还可以在定义替代变量值时使用载荷绑定来获取数据。

   • 过滤条件（可选）：您可以在触发器中创建一项规则，用于确定触发器是否会根据替代变量执行构建。

5. 点击创建以创建构建触发器。

gcloud

预览 — Webhook triggers: Cloud Build repositories (2nd gen) support

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 根据《云端数据处理附录》中所述的条款，您可以根据自己在访问 Google Cloud 时所受协议中所述的义务和限制，为此功能处理个人数据。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需创建 Webhook 触发器，请执行以下操作：

gcloud builds triggers create webhook \
  --region=REGION \
  --name=TRIGGER_NAME \
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --subscription-filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

其中：

• REGION 是触发器的区域。
• TRIGGER_NAME 是触发器的名称。
• PROJECT_ID 是您的 Cloud 项目 ID。
• CONNECTION_NAME 是主机连接的名称。
• REPO_NAME 是代码库的名称。
• SECRET_NAME 是存储在 Secret Manager
• SECRET_VERSION是与您的 与 Secret Manager 中存储的密钥相同
• 如果您使用 --inline-config），则 PATH_TO_INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
• 如果您想要将触发器设置为基于标记构建，则 TAG_NAME 是您的标记的名称。
• 如果您使用 --build-config，则 PATH_TO_BUILD_CONFIG 是构建配置文件的路径。
• 如果您想要将触发器设置为基于分支构建，则 BRANCH_NAME 是您的分支的名称。

（可选）获取 API 密钥

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

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

1. 在 Google Cloud 控制台中打开凭据页面：

   打开“凭据”页面

2. 点击创建凭据。

3. 点击 API 密钥。

   您会看到一个对话框，其中含有已创建的 API 密钥。记下您的 API 密钥。

4. 如果您要对产品应用的密钥进行限制，请点击限制密钥，以完成保护密钥的其他步骤。否则，请点击关闭。

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

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

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

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

   打开 IAM 页面

2. 可选：要查看 Google 提供的账号，请选择 选中包括 Google 提供的角色授权复选框。

3. 记下您想要的构建服务账号 授予此角色的权限。

4. 在 Google Cloud 控制台中打开 Secret Manager 页面：

   打开 Secret Manager 页面

5. 点击您的 Secret 名称。

   您会看到 Secret 详情页面。

   1. 点击权限标签页。

   2. 点击授予访问权限。

      您会看到授予访问权限面板。

   3. 在添加主账号部分中，添加与构建服务账号关联的电子邮件地址。

   4. 在分配角色部分中，选择 Secret Manager > Secret Manager Secret Accessor。

   5. 点击保存。

后续步骤

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