创建 Webhook 触发器

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

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

本页面概述了如何创建 Webhook 触发器。

准备工作

  • 启用 Cloud Build and Secret Manager API。

    启用 API

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

创建 webhook 触发器

控制台

如需使用 Google Cloud Console 创建 Webhook 触发器，请执行以下操作：

  1. 打开触发器页面

    打开“构建触发器”页面

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

  3. 点击创建触发器。

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

    • 名称：触发器的名称。
    • 说明（可选）：触发器的说明。
    • 事件：选择 Webhook 事件以设置触发器启动构建来响应传入的 Webhook 事件。

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

      • Secret：您需要使用 Secret 对传入的 Webhook 事件进行身份验证。您可以创建新的 Secret，也可以使用现有 Secret。

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

        1. 选择新建。

        2. 点击创建 Secret。

          您将看到创建 Webhook Secret 弹出框。

        3. 在 Secret 名称字段中，输入 Secret 名称。

        4. 点击创建 Secret 以保存您的 Secret，系统将自动在 Secret Manager 中创建并存储该 Secret。

        如需使用现有 Secret，请执行以下操作：

        1. 选择使用现有 Secret (Use existing)。
        2. 在 Secret 字段中，从下拉菜单选择要使用的 Secret 的名称，或者按照说明通过资源 ID 添加 Secret。
        3. 在 Secret 版本字段中，从下拉菜单选择您的 Secret 版本。

        如果您使用现有 Secret，则可能需要手动向您的 Cloud Build 服务帐号 ${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 事件。

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"

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

    • 来源（可选）：选择要在 webhook 触发器运行时构建的代码库。 如果您要指定内嵌构建配置，则无需指定以下来源。

    • 修订版本（可选）：选择要在 webhook 触发器运行时构建的分支或标记。 如果您要指定内嵌构建配置，则无需指定以下修订版本。

      • 分支（可选）：设置一个要在此分支上构建的触发器。必须指定字面量值。正则表达式不受支持。
      • 标记（可选）：设置一个要在此标记上构建的触发器。必须指定字面量值。正则表达式不受支持。

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

      • 类型：选择要用于构建的配置类型。
        • 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 Console 中编写您的构建配置文件。点击完成以保存您的构建配置。

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

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

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

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

      如需查看适用于 Webhook 触发器的过滤语法示例，请参阅使用 CEL 过滤构建事件。

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

gcloud

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

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

其中：

  • TRIGGER_NAME 是触发器的名称。
  • PATH_TO_REPO 是要对其调用构建的代码库的路径。例如 https://www.github.com/owner/repo。
  • PATH_TO_SECRET 是存储在 Secret Manager 中的 Secret 的路径。例如 projects/my-project/secrets/my-secret/versions/2。
  • 如果您使用 --inline-config），则 PATH_TO_INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
  • 如果您想要将触发器设置为基于标记构建，则 TAG_NAME 是您的标记的名称。
  • 如果您使用 --build-config，则 PATH_TO_BUILD_CONFIG 是构建配置文件的路径。
  • 如果您想要将触发器设置为基于分支构建，则 BRANCH_NAME 是您的分支的名称。

（可选）获取 API 密钥

您需要使用 API 密钥来验证传入的 Webhook 事件。

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

  1. 在 Google Cloud Console 中打开凭据页面：

    打开“凭据”页面

  2. 点击创建凭据。

  3. 点击 API 密钥。

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

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

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

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

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

  1. 在 Cloud Console 中打开 IAM 页面。

    打开 IAM 页面

  2. 记下您要向其授予该角色的 Cloud Build 服务帐号。

  3. 打开 Cloud Console 中的 Secret Manager 页面：

    打开 Secret Manager 页面

  4. 点击您的 Secret 名称。

    您会看到 Secret 详情页面。

    1. 点击右侧信息面板上的权限标签页。

    2. 点击添加主帐号。

    3. 在新建主帐号部分中，添加与您的 Cloud Build 服务帐号关联的电子邮件。

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

    5. 点击添加。

使用 CEL 过滤构建事件

Cloud Build 在构建资源中列出的字段上搭配使用 CEL 与变量 build，以便访问与构建事件关联的字段，例如触发器 ID、图片列表或替换值。您可以使用 filter 字符串，通过构建资源中列出的任何字段，来过滤通构建配置文件中的构建事件。如需查找与您的字段关联的具体语法，请参阅 cloudbuild.proto 文件。

按触发器 ID 过滤

要按触发器 ID 过滤，请使用 build.build_trigger_id 在 filter 字段中指定触发器 ID 的值，其中 trigger-id 是字符串形式的触发器 ID：

filter: build.build_trigger_id == trigger-id

按状态过滤

要按状态过滤，请使用 build.status 在 filter 字段中指定要过滤的构建状态。

以下示例展示了如何使用 filter 字段过滤状态为 SUCCESS 的构建事件：

filter: build.status == Build.Status.SUCCESS

您也可以过滤具有不同状态的构建。以下示例展示了如何使用 filter 字段过滤状态为 SUCCESS、FAILURE 或 TIMEOUT 的构建事件：

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

要查看您可以作为过滤依据的其他状态值，请参阅“构建资源参考”下的状态。

按标记过滤

要按标记过滤，请使用 build.tags 在 filter 字段中指定标记的值，其中 tag-name 是标记的名称：

filter: tag-name in build.tags

您可以使用 size 根据构建事件中指定的标记数量进行过滤。在以下示例中，filter 字段会过滤仅指定了两个标记且其中一个标记指定为 v1 的构建事件：

filter: size(build.tags) == 2 && "v1" in build.tags

按图片过滤

要按图片过滤，请使用 build.images 在 filter 字段中指定图片的值，其中 image-name 是 Container Registry 中列出的图片的全名，例如 gcr.io/example/image-one：

filter: image-name in build.images

在以下示例中，filter 会过滤将 gcr.io/example/image-one 或 gcr.io/example/image-two 指定为图片名称的构建事件：

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

按时间过滤

您可以在 filter 字段中指定以下某个选项，以根据构建的创建时间、开始时间或结束时间过滤构建事件：build.create_time、build.start_time 或 build.finish_time。

在以下示例中，filter 字段会使用 timestamp 来过滤创建构建的请求时间为 2020 年 7 月 20 日上午 6:00 的构建事件。

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

您还可以按时间比较过滤构建事件。在以下示例中，filter 字段会使用 timestamp 过滤开始时间介于 2020 年 7 月 20 日上午 6:00 到 2020 年 7 月 30 日上午 6:00 之间的构建事件。

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

如需详细了解 CEL 中的时区表示方式，请参阅时区的语言定义。

要按构建的持续时间进行过滤，您可以使用 duration 比较时间戳。 在以下示例中，filter 字段会使用 duration 过滤包含至少运行了五分钟的构建的构建事件：

filter: build.finish_time - build.start_time >= duration("5m")

按替换过滤

您可以使用 build.substitutions 在 filter 字段中指定替换变量，从而按替换进行过滤。在以下示例中，filter 字段会列出包含替代变量 substitution-variable 的构建，并检查 substitution-variable 是否与指定的 substitution-value 匹配：

filter: build.substitutions[substitution-variable] == substitution-value

其中：

  • substitution-variable 是替代变量的名称。
  • substitution-value 是替代变量值的名称。

您还可以按默认替换变量值进行过滤。在下面的示例中，filter 字段列出分支名称为 master 的构建，以及代码库名称为 github.com/user/my-example-repo 的构建。默认替换变量 BRANCH_NAME 和 REPO_NAME 将作为密钥传递给 build.substitutions：

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

如果要使用正则表达式过滤字符串，则可以使用内置的 matches 函数。在以下示例中，filter 字段过滤状态为 FAILURE 或 TIMEOUT 的构建，并且有一个构建替代变量 TAG_NAME，以及一个与正则表达式 v{DIGIT}.{DIGIT}.{3 DIGITS}) 匹配的值。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

要查看默认替换值的列表，请参阅使用默认替换。

后续步骤