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

第 1 代 第 2 代

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

借助网络钩子触发器，您可以指定内嵌 build 配置，而不是源代码库。通过此内嵌配置，您可以控制 Git 操作和构建工作流。如需在代码库事件发生时自动执行构建，您可以使用 Cloud Build 代码库触发器，该触发器可直接与 GitHub 和 GitLab 等提供商集成。

借助网络钩子触发器，您可以在创建触发器时定义内嵌 build 配置文件，而不是指定来源。内嵌 build 配置可让您控制 Git 操作，并让您定义 build 的其余部分。

本页面概述了如何创建 webhook 触发器以自动执行构建来响应 webhook 事件。

注意 ：如果您要创建在代码库事件发生时自动执行构建的触发器，我们建议您使用 Cloud Build 代码库触发器。使用 Cloud Build 代码库（第 2 代）的代码库触发器可以通过编程方式进行配置，并与源代码提供方集成，包括对 GitHub 和 GitLab 的支持。Cloud Build 代码库（第 2 代）还会使用 Secret Manager 代表您管理身份验证令牌和信息。代码库触发器可让您过滤传入事件并将构建状态发布回来源提供方，还可以配置为与专用网络搭配使用。如需了解详情，请参阅代码库概览页面。

准备工作

• 启用 Cloud Build 和 Secret Manager API（如果尚未启用）。

  启用 API 所需的角色

  如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

  启用 API

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

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

• 如果您的网络钩子触发器使用 Cloud Build 代码库作为来源，请确保您熟悉 Cloud Build 代码库。

创建 webhook 触发器

控制台

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

1. 打开触发器页面

   打开“构建触发器”页面

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

3. 点击创建触发器。

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

   • 名称：触发器的名称。

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

     • 如果与触发器关联的 build 配置文件指定了专用池，则 Cloud Build 会使用该专用池来运行 build。在这种情况下，您在触发器中指定的区域必须与您创建专用池的区域一致。
     • 如果与触发器关联的 build 配置文件未指定专用池，则 Cloud Build 会使用默认池在触发器所在的区域中运行 build。

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

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

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

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

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

     2. 点击创建 Secret。

        您会看到创建 Webhook 密钥对话框。

     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 角色。

        创建或选择密钥后，您会看到网络钩子网址预览。您的网址将包含由 Cloud Build 生成的 API 密钥和您的密钥。如果 Cloud Build 无法检索您的 API 密钥，您可以手动将 API 密钥添加到网址中；如果您还没有 API 密钥，可以了解如何获取 API 密钥。

        您可以使用该网址通过 POST 方法发出 HTTP 请求，从而调用 webhook 事件。

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

   • 来源（可选）：如果您指定的是内嵌 build 配置，则无需指定来源。否则，请执行以下操作：

     • 代码库世代：选择 第 2 代。

     • 代码库：从可用代码库列表中，选择要从中构建的代码库。代码库的区域必须与触发器的区域一致。

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

     • 评论控制：如果您选择拉取请求作为事件，请选择以下选项之一，以控制触发器是否自动调用构建：

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

       • 必需（所有者和协作者除外）：当代码库所有者或协作者创建或更新拉取请求时，系统会自动运行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求评论 /gcbrun 后，才会运行构建。

       • 必需：当任何贡献者创建或更新拉取请求时，只有在所有者或协作者对拉取请求评论 /gcbrun 后，才会运行构建。每次对拉取请求进行更改时，都会运行构建。

       • 不需要：当任何贡献者创建或更新拉取请求时，系统会自动运行构建。

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

     • 类型：选择要用于构建的配置类型。

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

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

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

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

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

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

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

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

   • 过滤条件（可选）：您可以在触发器中创建规则，以确定触发器是否将根据替代变量来运行构建。

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

gcloud

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

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

其中：

• TRIGGER_CONFIG_PATH 是触发器配置文件的路径。如果您使用触发器配置文件，则 name、description、region、secret、service-account、subscription-filter 和 substitution 字段必须保持未定义状态。如需了解详情，请参阅 Cloud Build 参考文档中的 BuildTrigger。
• TRIGGER_NAME 是触发器的名称。
• DESCRIPTION（可选）是触发器的说明。
• REGION 是触发器的区域。此值必须是“global”以外的区域。
• SECRET_NAME 是存储在 Secret Manager 中的 Secret 的名称。
• SECRET_VERSION 是与存储在 Secret Manager 中的 Secret 关联的版本。
• SERVICE_ACCOUNT 是用于运行与构建触发器相关的所有用户控制操作的服务账号。如果您未定义服务账号，Cloud Build 会使用默认的 Cloud Build 服务账号。
• PROJECT_ID 是 Google Cloud 项目 ID。
• CONNECTION_NAME 是主机连接的名称。
• REPO_NAME 是代码库的名称。
• PATH_TO_BUILD_CONFIG 是构建配置文件的路径。如果您的触发器引用 Cloud Build 代码库中的 build 配置文件，请使用此参数。如果您设置此参数，则无法为 Dockerfile 定义 inline-config 或使用参数。
• PATH_TO_INLINE_BUILD_CONFIG 是内嵌 build 配置的路径。如果触发器引用本地 build 配置文件，请使用此参数。如果您设置此参数，则无法为 Dockerfile 定义 build-config 或使用参数。
• DOCKERFILE 是 Dockerfile 的路径。如果您的触发器引用了 Dockerfile，请使用此参数。如果您设置了 Dockerfile 参数，则无法定义 build-config 或 inline-config。
• DOCKERFILE_DIR 是 Dockerfile 的目录。
• DOCKERFILE_IMAGE 是 Cloud Build 构建的 Docker 映像的名称。
• 如果您要设置触发器以在分支上构建，则 BRANCH_NAME 是分支的名称。如果您设置了此参数，则无法定义 tag。
• 如果您要设置触发器以基于标记进行构建，则 TAG_NAME 是标记的名称。如果您设置了此参数，则无法定义 branch。
• SUBSTITUTION（可选）是要在构建规范中替换的参数。例如 _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'。
• FILTER（可选）是触发器的 CEL 过滤表达式，例如 '_SUB_ONE == "prod"'。
• （可选）如果命令中存在 --require-approval，则 Cloud Build 需要手动批准触发的 build。

调用 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 角色

在创建 webhook 触发器期间配置 Secret 时，在大多数情况下，Cloud Build 会自动向需要该角色的服务账号授予 Secret Manager Secret Accessor 角色。不过，如果您使用现有 Secret，可能还需要手动向 Cloud Build 服务账号授予 Secret Manager Secret Accessor 角色：

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. 点击保存。

（可选）获取 API 密钥

如需对传入的网络钩子事件进行身份验证，您需要一个 API 密钥。此 API 密钥是您在配置 webhook 触发器时选择的密钥的一部分。如果您还没有 API 密钥，或者 Cloud Build 在 Google Cloud 控制台中配置 Secret 时无法检索到 API 密钥，则可以手动创建 API 密钥：

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

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

   打开“凭据”页面

2. 点击创建凭据。

3. 点击 API 密钥。

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

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

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

后续步骤

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