自动构建以响应 Pub/Sub 事件

借助 Cloud Build Pub/Sub 触发器，您可以执行构建来响应通过 Pub/Sub 发布的 Google Cloud 事件。您可以使用 Pub/Sub 事件中的信息对构建进行参数化，并确定是否应执行构建来响应事件。 Pub/Sub 触发器可以配置为侦听任何 Pub/Sub 主题。

本页面介绍如何创建 Pub/Sub 触发器来自动执行构建，以响应 Artifact Registry、Container Registry（已弃用）和 Cloud Storage 上的事件。

准备工作

启用 Cloud Build API。
启用 API

确保您的源代码包含代码库中的构建配置文件或 Dockerfile。
如需使用此页面上的 gcloud 命令，请安装 Google Cloud CLI。

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

创建构建触发器来响应 Artifact Registry 事件

您可以创建一个 Pub/Sub 触发器来响应 Artifact Registry 事件，例如推送、标记或删除映像。本部分介绍如何创建 Pub/Sub 触发器，该触发器会在新标记推送到现有映像时调用构建。如果您不熟悉 Artifact Registry，请参阅 Artifact Registry 概览。

控制台

如需创建一个触发器来监听 Google Cloud 控制台中推送到 Artifact Registry 中现有映像的新标记，请执行以下操作：

打开触发器页面

打开“触发器”页面
从页面顶部选择您的项目，然后点击打开。
点击创建触发器。
输入以下触发器设置：
- 名称：输入触发器的名称。
- 区域：为触发器选择区域。
  - 如果与触发器关联的构建配置文件指定了专用池，则 Cloud Build 会使用专用池来运行构建。在这种情况下，您在触发器中指定的区域必须与创建专用池的区域一致。
  - 如果与触发器关联的构建配置文件未指定专用池，则 Cloud Build 将使用默认池在触发器所在的区域中运行构建。
- 说明（可选）：输入触发器的说明。
- 事件：选择 Pub/Sub 消息作为用于调用触发器的事件。
- 订阅：选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。
  - Pub/Sub 主题：从下拉菜单中选择 gcr 主题，或按照配置 Pub/Sub 通知中的说明手动创建主题。
  注意：创建触发器后，系统会自动为您创建该触发器的订阅。您可以在 Pub/Sub 订阅页面上查看您的订阅。
- 来源：选择要在 Pub/Sub 触发器运行时构建的来源。您可以指定第 1 代或第 2 代作为来源。
  
  注意：代码库的区域必须与触发器的区域一致。
  - 代码库：从可用代码库列表中，选择所需的代码库。
  - 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。
  - 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：
    
    警告：对代码库具有读取访问权限的任何用户都可以提交拉取请求，这可能会执行包含拉取请求中的源代码更改的构建。如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。如需详细了解触发器的构建时权限，请参阅构建触发器和 Cloud Build 服务账号。
    - 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。
    - 必需：如果任何贡献者创建或更新拉取请求，则只有在所有者或协作者对拉取请求添加注释 /gcbrun 后，系统才会执行构建。每次对拉取请求进行更改时，系统都会执行构建。
    - 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。
- 配置：选择构建配置文件（位于远程代码库），或创建要用于构建的内嵌构建配置文件。
  - 类型：选择要用于构建的配置类型。
    - 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）作为配置选项，则可以指定内嵌构建配置。点击打开编辑器，使用 YAML 或 JSON 语法在 Google Cloud 控制台中编写构建配置文件。点击完成以保存您的构建配置。
      
      注意：内嵌构建配置支持不适用于 Dockerfile 或 buildpack。
- 替代变量（可选）：如果您选择了构建配置文件作为构建配置选项，则您可以选择使用此字段来定义特定于触发器的替代变量。
  
  在以下示例中，我们想要通过与 gcr 事件关联的载荷和操作获取映像标记的名称。为此，请使用载荷绑定创建替代变量。
  
  指定以下变量和值：
  
  变量名称 变量值
  
  _IMAGE_TAG $(body.message.data.tag)
  
  _ACTION $(body.message.data.action)
  
  body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例，请参阅通知示例。
  
  注意：虽然定义替代变量是可选的，但如果您要对 Pub/Sub 消息设置自定义过滤条件，则这些变量是必需的（请参阅过滤条件了解详情）。
- 过滤条件（可选）：您可以在触发器中创建过滤条件，以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true，才能执行构建。
  
  在包含多个消息的主题上设置 Pub/Sub 触发器时，我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险，请参阅与未过滤的触发器有关的风险。
  
  在以下示例中，我们希望触发器在新标记推送到现有映像时执行构建。我们使用过滤条件运算符来检查 _IMAGE_TAG 变量是否与现有标记名称匹配，以及 _ACTION 变量是否与 INSERT 匹配，以查找新添加的数据。
  
  指定以下内容作为过滤条件：
  - _IMAGE_TAG != ""
  - _ACTION == INSERT
  注意：您还可以通过指定以下布尔运算符来嵌套条件：&& (and) 和 || (or)。不支持 ! (not) 符号。
  Pub/Sub 触发器中的过滤语法使用通用表达式语言 (CEL) 进行表达式求值。如需详细了解 CEL，请参阅 cel-spec 代码库。

变量名称	变量值
`_IMAGE_TAG`	`$(body.message.data.tag)`
`_ACTION`	`$(body.message.data.action)`

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

gcloud

如需创建一个触发器，用于通过 gcloud 命令监听推送到 Artifact Registry 中现有映像的新标记，请执行以下操作：

打开一个终端窗口。

运行 gcloud 命令，在项目中创建一个构建触发器。在以下示例中，触发器配置为根据替代变量 _IMAGE_TAG 定义的指定载荷，响应标记与 prod 匹配且操作与 INSERT 匹配的构建。

 gcloud builds triggers create pubsub \
   --region=REGION \
   --name=TRIGGER_NAME \
   --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
   --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
   --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
   --substitutions=\
     '_IMAGE_TAG_="$(body.message.data.tag)",' \
     '_ACTION="$(body.message.data.action)"' \
   --subscription-filter='_IMAGE_TAG == "" && _ACTION == "INSERT"' \
   --tag=TAG_NAME  # or --branch=BRANCH_NAME

其中：

REGION 是触发器的区域。
TRIGGER_NAME 是触发器的名称。
PROJECT_ID 是您的 Cloud 项目的 ID。
CONNECTION_NAME 是您的主机连接的名称。
REPO_NAME 是代码库的名称。
TOPIC_NAME 是您订阅的 Pub/Sub 主题的名称。
BUILD_CONFIG 是构建配置文件的路径。
INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
如果您想要将触发器设置为基于标记构建，则 TAG_NAME 是您的标记的名称。
如果您想要将触发器设置为基于分支构建，则 BRANCH_NAME 是您的分支的名称。

创建构建触发器来响应 Container Registry 事件

您可以创建 Pub/Sub 触发器来响应 Container Registry 事件，例如推送、标记或删除映像。本部分介绍如何创建 Pub/Sub 触发器，该触发器会在映像与自定义过滤条件设置的标记匹配时调用构建。如果您不熟悉 Container Registry，请参阅 Container Registry 快速入门，了解如何使用标记推送和拉取映像。

控制台

如需使用 Google Cloud 控制台创建一个触发器来监听 Container Registry 中的映像推送并基于标记名称进行匹配，请执行以下操作：

打开触发器页面

打开“触发器”页面
从页面顶部选择您的项目，然后点击打开。
点击创建触发器。
输入以下触发器设置：
- 名称：输入触发器的名称。
- 区域：为触发器选择区域。
  - 如果与触发器关联的构建配置文件指定了专用池，则 Cloud Build 会使用专用池来运行构建。在这种情况下，您在触发器中指定的区域必须与创建专用池的区域一致。
  - 如果与触发器关联的构建配置文件未指定专用池，则 Cloud Build 将使用默认池在触发器所在的区域中运行构建。
- 说明（可选）：输入触发器的说明。
- 事件：选择 Pub/Sub 消息作为用于调用触发器的事件。
- 订阅：选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。
  - Pub/Sub 主题：从下拉菜单中选择 gcr 主题，或按照配置 Pub/Sub 通知中的说明手动创建主题。
  注意：创建触发器后，系统会自动为您创建该触发器的订阅。您可以在 Pub/Sub 订阅页面上查看您的订阅。
- 来源：选择要在 Pub/Sub 触发器运行时构建的来源。您可以指定第 1 代或第 2 代作为来源。
  
  注意：代码库的区域必须与触发器的区域一致。
  - 代码库：从可用代码库列表中，选择所需的代码库。
  - 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。
  - 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：
    
    警告：对代码库具有读取访问权限的任何用户都可以提交拉取请求，这可能会执行包含拉取请求中的源代码更改的构建。如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。如需详细了解触发器的构建时权限，请参阅构建触发器和 Cloud Build 服务账号。
    - 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。
    - 必需：如果任何贡献者创建或更新拉取请求，则只有在所有者或协作者对拉取请求添加注释 /gcbrun 后，系统才会执行构建。每次对拉取请求进行更改时，系统都会执行构建。
    - 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。
- 配置：选择构建配置文件（位于远程代码库），或创建要用于构建的内嵌构建配置文件。
  - 类型：选择要用于构建的配置类型。
    - 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）作为配置选项，则可以指定内嵌构建配置。点击打开编辑器，使用 YAML 或 JSON 语法在 Google Cloud 控制台中编写构建配置文件。点击完成以保存您的构建配置。
      
      注意：内嵌构建配置支持不适用于 Dockerfile 或 buildpack。
- 替代变量（可选）：如果您选择了构建配置文件作为构建配置选项，则您可以选择使用此字段来定义特定于触发器的替代变量。
  
  在以下示例中，我们想要通过与 gcr 事件关联的载荷和操作获取映像标记的名称。为此，请使用载荷绑定创建替代变量。
  
  指定以下变量和值：
  
  变量名称 变量值
  
  _IMAGE_TAG $(body.message.data.tag)
  
  _ACTION $(body.message.data.action)
  
  body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例，请参阅通知示例。
  
  注意：虽然定义替代变量是可选的，但如果您要对 Pub/Sub 消息设置自定义过滤条件，则这些变量是必需的（请参阅过滤条件了解详情）。
- 过滤条件（可选）：您可以在触发器中创建过滤条件，以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true，才能执行构建。
  
  在包含多个消息的主题上设置 Pub/Sub 触发器时，我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险，请参阅与未过滤的触发器有关的风险。
  
  在以下示例中，我们希望触发器在 _IMAGE_TAG 标记变量的名称与特定标记名称（例如 prod）匹配时执行构建。您可以将过滤条件运算符指定为“==”，以进行完全匹配。您还可以检查与 gcr 事件关联的操作。例如，您可以将 _ACTION 指定为 INSERT 以查找新添加的数据。
  
  指定以下内容作为过滤条件：
  - _IMAGE_TAG.matches(prod)
  - _ACTION.matches(INSERT)
  注意：您还可以通过指定以下布尔运算符来嵌套条件：&& (and) 和 || (or)。不支持 ! (not) 符号。
  Pub/Sub 触发器中的过滤语法使用通用表达式语言 (CEL) 进行表达式求值。如需详细了解 CEL，请参阅 cel-spec 代码库。如需查看可应用于 Pub/Sub 触发器的更多过滤语法示例，请参阅过滤构建。

变量名称	变量值
`_IMAGE_TAG`	`$(body.message.data.tag)`
`_ACTION`	`$(body.message.data.action)`

点击创建以创建构建触发器

gcloud

创建构建触发器来响应 Cloud Storage 事件

您可以创建一个 Pub/Sub 触发器来响应 Cloud Storage 事件（例如，新的二进制文件被推送到现有存储桶时）。本部分介绍如何创建 Pub/Sub 触发器，该触发器会在将新二进制文件部署到上传的存储桶时使用构建进行响应。如果您不熟悉 Cloud Storage，请参阅快速入门。

控制台

如需创建使用 Google Cloud 控制台来监听 Cloud Storage 事件的触发器，请执行以下操作：

打开触发器页面

打开“触发器”页面
从页面顶部选择您的项目，然后点击打开。
点击创建触发器。
输入以下触发器设置：
- 名称：输入触发器的名称。
- 区域：为触发器选择区域。
  - 如果与触发器关联的构建配置文件指定了专用池，则 Cloud Build 会使用专用池来运行构建。在这种情况下，您在触发器中指定的区域必须与创建专用池的区域一致。
  - 如果与触发器关联的构建配置文件未指定专用池，则 Cloud Build 将使用默认池在触发器所在的区域中运行构建。
- 说明（可选）：输入触发器的说明。
- 事件：选择 Pub/Sub 消息作为用于调用触发器的事件。
- 订阅：选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。
  - Pub/Sub 主题：从下拉菜单中选择 gcs 主题，或按照为 Cloud Storage 配置 Pub/Sub 通知中的说明手动创建主题。
  注意：创建触发器后，系统会自动为您创建该触发器的订阅。您可以在 Pub/Sub 订阅页面上查看您的订阅。
- 来源：选择要在 Pub/Sub 触发器运行时构建的来源。您可以指定第 1 代或第 2 代作为来源。
  
  注意：代码库的区域必须与触发器的区域一致。
  - 代码库：从可用代码库列表中，选择所需的代码库。
  - 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。
  - 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：
    
    警告：对代码库具有读取访问权限的任何用户都可以提交拉取请求，这可能会执行包含拉取请求中的源代码更改的构建。如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。如需详细了解触发器的构建时权限，请参阅构建触发器和 Cloud Build 服务账号。
    - 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。
    - 必需：如果任何贡献者创建或更新拉取请求，则只有在所有者或协作者对拉取请求添加注释 /gcbrun 后，系统才会执行构建。每次对拉取请求进行更改时，系统都会执行构建。
    - 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。
- 配置：选择构建配置文件（位于远程代码库），或创建要用于构建的内嵌构建配置文件。
  - 类型：选择要用于构建的配置类型。
    - 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）作为配置选项，则可以指定内嵌构建配置。点击打开编辑器，使用 YAML 或 JSON 语法在 Google Cloud 控制台中编写构建配置文件。点击完成以保存您的构建配置。
      
      注意：内嵌构建配置支持不适用于 Dockerfile 或 buildpack。
- 替代变量（可选）：如果您选择了构建配置文件作为构建配置选项，则您可以选择使用此字段来定义特定于触发器的替代变量。
  
  在此示例中，我们想要在新二进制文件上传到存储桶后监控其部署。如需获取此数据，我们可以使用载荷绑定创建替代变量。
  
  指定以下变量和值：
  
  变量名称 变量值
  
  _EVENT_TYPE $(body.message.attributes.eventType)
  
  _BUCKET_ID $(body.message.attributes.bucketId)
  
  _OBJECT_ID $(body.message.attributes.objectId)
  
  body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例，请参阅通知示例。
  
  注意：虽然定义替代变量是可选的，但如果您要对 Pub/Sub 消息设置自定义过滤条件，则这些变量是必需的（请参阅过滤条件了解详情）。
- 过滤条件（可选）：您可以在触发器中创建过滤条件，以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true，才能执行构建。
  
  在包含多个消息的主题上设置 Pub/Sub 触发器时，我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险，请参阅与未过滤的触发器有关的风险。
  
  我们想要触发器在新二进制文件部署到特定存储桶时执行构建，因此可以使用“==”运算符来检查是否完全匹配。如果您想要按正则表达式进行匹配，则还可以使用“matches”关键字。
  
  指定以下内容作为过滤条件：
  - _EVENT_TYPE == OBJECT_FINALIZE
  - _OBJECT_ID 与 ^<object-id>$ 匹配
  - _BUCKET_ID 与 ^<bucket-id>$ 匹配

变量名称	变量值
`_EVENT_TYPE`	`$(body.message.attributes.eventType)`
`_BUCKET_ID`	`$(body.message.attributes.bucketId)`
`_OBJECT_ID`	`$(body.message.attributes.objectId)`

点击创建以创建构建触发器

gcloud

与未过滤的触发器有关的风险

如果您尚未对 Pub/Sub 触发器配置过滤条件，并且触发器修改了工件或对象，导致无意中将新消息发布到触发器正侦听的主题，则触发器最终可能会调用无限数量的构建。例如，如果触发器执行以下操作，则触发器可能会调用无限数量的构建：

指向 gcr 主题。
在 gcr 中创建任何映像或标记。
指向存储桶中特定对象的 gcs 主题并修改该对象。

如果遇到无限循环，您可以删除触发器或将触发器更新为指向单独的主题，以避免为调用的每个构建支付额外费用。

后续步骤

了解如何使用 gcloud 命令或 Cloud Build API 手动启动构建。
了解如何创建和管理触发器。
了解如何查看构建结果。
了解如何排查构建错误。