创建和管理构建触发器

无论您何时更改源代码,Cloud Build 触发器都会自动启动构建。您可以将触发器配置为针对源代码库的任何更改或仅符合特定条件的更改来构建代码。

本页面介绍了如何关联到 GitHub 和 Bitbucket 等源代码库,以及如何创建构建触发器以在代码库中构建代码。

准备工作

  • 启用 Cloud Build API。

    启用 API

  • 您需要拥有项目的 Cloud Build Editor (roles/cloudbuild.builds.editor) 角色才能创建触发器。
  • 您需要 Cloud Source Repositories、GitHub 或 Bitbucket 中的源代码。
  • 您需要 DockerfileCloud Build 配置文件

关联到源代码库

您必须先将 Cloud Build 关联到源代码库,然后才能在该代码库中构建代码。默认情况下,Cloud Source Repositories 中的代码库与 Cloud Build 关联。您可以在 Cloud Source Repositories 中为您的代码库直接创建触发器,而无需手动关联到代码库。

如果要关联外部代码库(例如托管在 GitHub 或 Bitbucket 上的代码库),您需要对代码库具有管理员级别的权限,这样才能将您的代码库最初连接到 Cloud Build。在已连接到 Cloud Build 的代码库中创建触发器时不需要具有管理员权限。

如需连接到 GitHub 或 Bitbucket,请完成以下步骤:

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“触发器”页面

  2. 选择您的项目,然后点击打开

  3. 区域下拉菜单中选择要在哪个区域创建触发器。

  4. 点击关联代码库

  5. 选择您已在其中存储源代码的代码库。

    如果您选择 GitHub(已镜像)Bitbucket(已镜像)作为源代码库,则 Cloud Build 会镜像 Cloud Source Repositories 中的代码库,并使用已镜像的代码库执行其所有操作。

  6. 点击继续

  7. 使用您的用户名和密码向您的源代码库进行身份验证。

  8. 从可用代码库列表中,选择所需的代码库,然后点击关联

    对于外部代码库(例如 GitHub 和 Bitbucket),您必须拥有正在处理的 Google Cloud 项目的所有者级权限。

  9. 点击创建触发器继续创建构建触发器,以便对代码库中的源代码进行自动构建;或点击完成

创建构建触发器

控制台

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“触发器”页面

  2. 从页面顶部的项目选择器下拉菜单中选择您的项目。

  3. 点击打开

  4. 点击创建触发器

  5. 输入以下触发器设置:

    • 名称:输入触发器的名称。

    • 区域:为触发器选择区域

      如果与触发器关联的构建配置文件指定了专用池,则您为触发器选择的区域必须与该专用池的区域一致。

      如果您选择 global 作为区域,则 Cloud Build 会使用构建配置文件中指定的区域来运行构建。该池可以是专用池所在的区域(如果您在构建配置文件中指定了专用池),或者是全局默认池(如果您没有指定专用池)。

    • 说明(可选):输入触发器的说明。

    • 事件:选择用于调用触发器的代码库事件。

      • 推送到分支:设置触发器,以便基于对特定分支的提交启动构建。

      • 推送新标记:将触发器设置为以基于包含特定标记的提交启动构建。

      • 拉取请求:设置触发器以基于对拉取请求的提交启动构建。

    • 来源:选择第 1 代第 2 代作为来源。 选择第 2 代作为来源时,您只能从 GitHub 和 GitHub Enterprise 连接代码库。如需了解详情,请参阅 Cloud Build 代码库

      • 代码库:从可用代码库列表中,选择所需的代码库。如需关联新的代码库,请参阅关联到源代码库
      • 分支标记:指定要匹配分支或标记值的正则表达式。标记中不能使用正斜杠 (/)。如需详细了解可接受的正则表达式语法,请参阅 RE2 语法

        执行构建时,Cloud Build 会将代码库的内容复制到 /workspace(Cloud Build 的默认工作目录)。如需详细了解工作目录,请参阅构建配置概览页面

        如需仅允许来自特定来源的构建,请为允许的集成设置组织政策 (constraints/cloudbuild.allowedIntegrations),以拒绝与触发器中定义的来源互动。组织政策会替换触发器,并且您的构建不会执行。如需了解详情,请参阅项目的组织政策构建门控

    • 包含的文件(可选):如果更改影响至少一个文件,则会调用构建。您可以使用 glob 字符串指定带有通配符的多个文件。可接受的通配符包括 Go Match 支持的字符、**变体

    • 忽略的文件(可选):如果更改只影响被忽略的文件,则不会调用构建。您可以使用 glob 字符串指定带有通配符的多个文件。可接受的通配符包括 Go Match 支持的字符、**变体

      如果指定的文件同时存在于包含的文件忽略的文件中,则对该文件的更改不会调用构建。假设您在忽略的文件中指定 **/README.md 以忽略任意目录中的 README.md,并在包含的文件中指定 src/* 以在对文件夹 src/ 中的任意文件进行更改时启动构建。现在,如果您对 src/README.md 进行更改,则 Cloud Build 将不会启动构建。每次将更改推送到源代码时,Cloud Build 都会查看包含的文件和忽略的文件中已更改的文件,以确定是否应触发构建:

      • 如果您将更改推送到现有分支上的代码库,Cloud Build 将查看您刚刚推送的提交和分支先前指向的提交之间更改的文件。
      • 如果您的代码库是 Cloud Source Repository,并且您将更改推送到新创建的分支,则 Cloud Build 会将代码库中的所有文件视为已更改的文件。
      • 如果删除分支,则 Cloud Build 不会启动构建。
    • 配置:选择位于远程代码库中的构建配置文件,或创建要用于构建的内嵌构建配置文件。

      • 类型:选择要用于构建的配置类型。
        • Cloud Build 配置文件(yaml 或 json):为您的配置使用构建配置文件。
        • Dockerfile:为您的配置使用 Dockerfile
        • Buildpack:为您的配置使用 buildpack
      • 位置:为您的配置指定位置。

        • 代码库:如果您的配置文件位于远程代码库中,请提供构建配置文件Dockerfile 目录或 buildpack 目录的位置。如果您的构建配置类型是 Dockerfile 或 buildpack,则需要为生成的映像提供名称,还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后,您会看到您的构建将执行的 docker buildpack 命令的预览。
        • Buildpack 环境变量(可选):如果您选择了 buildpacks 作为配置类型,请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量,请参阅环境变量
        • 内嵌:如果您选择了 Cloud Build 配置文件(yaml 或 json)作为配置选项,则可以指定内嵌构建配置。点击打开编辑器,使用 YAML 或 JSON 语法在 Google Cloud 控制台中编写构建配置文件。点击完成以保存您的构建配置。

    • 使用专用池:如果您选择了 Dockerfile 作为配置选项,则会显示此字段。如果您在专用池中运行构建,请选中此复选框。

    • 专用池:如果您选择了使用专用池,请指定专用池的资源名称,格式为 projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID

    • 替代变量(可选):如果您选择了 Cloud Build 配置文件作为构建配置选项,则您可以选择使用此字段定义特定于触发器的替代变量。例如,假设您要创建多个触发器,其中每个触发器都会将您的应用部署到特定环境。您可以在构建配置文件中指定将应用部署到某个环境,然后使用该字段定义替代变量,用于指定相应触发器应部署到哪个环境。如需了解如何在构建配置文件中指定替换值,请参阅替代变量值

    • 批准(可选):勾选此复选框可要求在构建执行前获得批准。

    • 服务账号:选择调用触发器时使用的服务账号。如果您未选择服务账号,则使用默认的 Cloud Build 服务账号

  6. 点击创建以保存您的构建触发器。

gcloud

如需在源代码位于 Cloud Source Repositories 的情况下创建触发器,请运行以下命令

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

其中:

  • REPO_NAME 是代码库的名称。
  • BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
  • TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
  • BUILD_CONFIG_FILE 是构建配置文件的路径。

  • SERVICE_ACCOUNT 是与您的服务账号相关联的电子邮件地址。如果不添加此标志,则系统会使用默认的 Cloud Build 服务账号

  • [可选] --require-approval 是一个要添加的标志,用于将触发器配置为需要获得批准。

如需查看完整的标志列表,请参阅 gcloud 参考,了解如何为 Cloud Source Repositories 创建触发器

如需在源代码位于 GitHub 的情况下创建触发器,请运行以下命令

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

其中:

  • REGION 是触发器的区域
  • REPO_NAME 是代码库的名称。
  • REPO_OWNER 是代码库所有者的用户名。
  • BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
  • TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
  • BUILD_CONFIG_FILE 是构建配置文件的路径。
  • SERVICE_ACCOUNT 是与您的服务账号相关联的电子邮件地址。如果不添加此标志,则系统会使用默认的 Cloud Build 服务账号
  • [可选] --require-approval 是一个要添加的标志,用于将触发器配置为需要获得批准。
  • [可选] --include-logs-with-status 是您可以指定的标志,用于显示代码库的构建日志。GitHubGitHub Enterprise 代码库中的 build 支持此标志。

如需查看完整的标志列表,请参阅 gcloud 参考,了解如何为 GitHub 创建触发器

运行 gcloud 命令以使用 Cloud Source Repositories 或 GitHub 创建触发器后,您应该会看到如下所示的输出:

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

测试构建触发器

如需手动测试构建触发器,请执行以下操作:

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“触发器”页面

  2. 在列表中找到您的触发器,然后点击运行触发器

跳过构建触发器

在某些情况下,您可能想要更改源代码,但不希望调用构建。例如,您可能不希望在更新文档或配置文件时调用构建。

在此类情况下,您可以在提交消息中包含 [skip ci][ci skip],这样就不会调用构建。

如果您想要以后基于该提交运行构建,请使用触发器页面中的运行触发器按钮。

在构建中包含代码库历史记录

为了在 Git 代码库上构建源代码,Cloud Build 会对代码库执行浅层克隆。也就是说,只有启动了构建的单个提交才会在要进行构建的工作空间中签出。Cloud Build 不会签出任何其他分支或历史记录。这样做是为了提高效率,如此一来,构建便不必仅为了构建单个提交而等待获取整个代码库和历史记录。

如果要在构建中包含更多代码库的历史记录,请在构建配置文件中添加一个构建步骤以“撤销浅层”克隆。例如:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

如需详细了解 git fetch,请参阅 Git 参考。如需了解如何编写构建配置文件,请参阅构建配置概览

重新提交构建以进行批准

如果您的 build 被拒,您可以在 Google Cloud 控制台中按照以下步骤重新提交该 build 以供审批:

  1. 在 Google Cloud 控制台中打开 Cloud Build 历史记录页面。

    打开“Cloud Build 记录”页面

  2. 点击您要重新提交以进行批准的构建的 ID。

  3. 点击页面顶部的重新构建以重新提交您的构建进行批准。

具有权限的用户批准您的构建后,构建将启动。如需详细了解 Cloud Build 审批,请参阅构建审批门槛

更新构建触发器

控制台

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“构建触发器”页面

  2. 从页面顶部的项目选择器下拉菜单中选择您的项目。

  3. 点击打开

  4. 找到您要更新的触发器所在的行。

  5. 点击位于该行右端的菜单(垂直省略号)。

  6. 选择修改

gcloud

如需更新触发器,请执行以下操作:

  1. 导出要更新的触发器:

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    其中:

    • TRIGGER_NAME 是触发器的名称。
    • EXPORT_PATH 是您要将触发器导出到的文件路径。例如,您可以指定 examples/trigger.yaml 作为文件路径。请注意,触发器的文件名应包含 .yaml 扩展名。
  2. 打开包含已导出触发器的文件。

    您的文件将如下所示:

     createTime: '2022-05-26T21:56:11.830784153Z'
     filename: cloudbuild.yaml
     github:
       name: cloud-build-example
       owner: main
       push:
         branch: master
     id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
     # remove field name and value to not show build logs
     includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
     name: trigger-001
    
  3. 手动修改文件以更新触发器。

    如需查看您可以为触发器添加或移除的字段,请参阅触发器资源

  4. 保存文件。

  5. 导入您的触发器:

     gcloud builds triggers import --source=IMPORT_PATH
    

    其中:

    • IMPORT_PATH 是您要导入的触发器的文件路径。

您的构建触发器现已更新。

停用构建触发器

控制台

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“构建触发器”页面

  2. 从页面顶部的项目选择器下拉菜单中选择您的项目。

  3. 点击打开

  4. 找到您要停用的触发器所在的行。

  5. 点击位于该行右端的菜单(垂直省略号)。

  6. 选择 Disable(停用)。

gcloud

要停用触发器,请执行以下操作:

  1. 导出您要停用的触发器:

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    其中:

    • TRIGGER_NAME 是触发器的名称。
    • EXPORT_PATH 是您要将触发器导出到的文件路径。例如,您可以指定 examples/trigger.yaml 作为文件路径。请注意,触发器的文件名应包含 .yaml 扩展名。
  2. 打开包含已导出触发器的文件。

    您的文件将如下所示:

     createTime: '2020-02-21T20:02:50.215599013Z'
     description: Push to any branch
     filename: cloudbuild.yaml
     github:
       name: example-repo-name
       owner: example-owner
       push:
         branch: .*
     id: example-id
     name: Push-to-any-branch
     tags:
     - github-default-push-trigger
    
  3. disabled 字段添加到文件末尾,并将值设置为 True

     disabled: True
    
  4. 保存文件。

  5. 导入您的触发器:

     gcloud builds triggers import --source=IMPORT_PATH
    

    其中:

    • IMPORT_PATH 是您要导入的触发器的文件路径。

您的构建触发器现已停用。

停用触发器不会删除触发器。如需删除触发器,请参阅删除构建触发器。要重新启用触发器,可将状态更改为已启用

删除构建触发器

控制台

  1. 在 Google Cloud 控制台中打开触发器页面。

    打开“构建触发器”页面

  2. 从页面顶部的项目选择器下拉菜单中选择您的项目。

  3. 点击打开

  4. 找到您要删除的触发器所在的行。

  5. 点击位于该行右端的菜单(垂直省略号)。

  6. 选择删除

gcloud

如需删除触发器,请运行以下命令:

  gcloud builds triggers delete TRIGGER_NAME

其中:

  • TRIGGER_NAME 是触发器的名称。

如需查看完整的标志列表,请参阅 gcloud 参考,了解如何删除触发器

构建触发器的安全隐患

默认情况下,构建触发器使用 Cloud Build 服务帐号执行构建,这可以为使用触发器执行构建的用户提供构建时权限。使用构建触发器时,请注意以下安全隐患:

  • 无权访问您的 Cloud 项目但有权写入与该项目中构建触发器关联的代码库的用户将有权更改正在构建的代码。
  • 如果您使用的是 GitHub 拉取请求触发器,则有权读取代码库的任何用户都可以提交拉取请求,这可能会执行其中包含拉取请求中的代码更改的构建。如需了解如何停用 GitHub 拉取请求触发器的此行为,请参阅创建 GitHub 触发器

创建一个仅包含触发器所需角色的服务帐号是一种很好的安全做法。如需了解详情,请参阅配置用户指定的服务帐号。如需详细了解 Cloud Build 服务帐号及其关联权限,请参阅 Cloud Build 服务帐号

后续步骤