连接到 Cloud Build

本页面详细介绍了如何使用 Cloud Build 配置文件和 Secure Source Manager 代码库中的触发器 YAML 文件，从 Secure Source Manager 自动调用构建。

默认情况下，Secure Source Manager 使用 Google 代管式服务代理与 Cloud Build 和其他资源进行交互。为了隔离团队 权限，我们建议您通过关联 一个 用户代管式服务 与您的代码库来配置每个代码库的身份。 Secure Source Manager 使用与代码库关联的用户代管式服务账号来触发构建。

与默认服务代理不同，您可以为用户代管式服务账号配置对自定义 Cloud Build 服务账号的 iam.serviceAccounts.actAs 权限。这样，您就可以使用自定义服务账号运行构建，同时将构建权限限制在该代码库中。

准备工作

  1. 创建 Secure Source Manager 实例。
  2. 创建 Secure Source Manager 代码库。

  3. 配置 Cloud Build 用户指定的服务账号。 如需让 Cloud Build 从 Secure Source Manager 代码库中读取内容， 请向 Cloud Build 服务帐号（默认服务账号或用户管理的服务账号）授予以下角色：

    • Secure Source Manager 实例的 Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor)。
    • 代码库的 Secure Source Manager Repository Reader 。

    根据您的使用场景，Cloud Build 服务帐号可能需要其他角色，例如：

    • 如需将构建日志存储在 Cloud Logging 中，请向 Cloud Build 服务帐号授予 Logs Writer 角色 (roles/logging.logWriter)。
    • 如需访问 Secret Manager 中的 Secret，请向 Cloud Build 服务帐号授予 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。

    如需了解构建日志，请参阅设置构建日志。

  4. 如果您的构建在工作器池中运行，请向运行构建的项目中的代码库的用户代管式服务账号授予 Cloud Build WorkerPool User 角色 (roles/cloudbuild.workerPoolUser)。

所需角色

如需获得将 Secure Source Manager 代码库连接到 Cloud Build 所需的权限，请让您的管理员为您授予以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

如需了解如何授予 Secure Source Manager 角色， 请参阅 使用 IAM 进行访问权限控制 和 向用户授予实例访问权限。

所需的服务帐号角色

如需将 Secure Source Manager 连接到 Cloud Build，您必须为每个代码库的身份配置 IAM 权限。

每个代码库的身份设置

如需使用每个代码库的身份，您必须配置权限。

  1. 用户：配置代码库服务帐号的用户需要对用户代管式服务服务帐号拥有 Service Account User 角色 (roles/iam.serviceAccountUser)。系统会在创建或更新代码库期间检查此权限。

  2. Secure Source Manager 服务代理：向代码库项目的 Secure Source Manager 服务代理授予用户代管式服务账号的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    Secure Source Manager 服务代理电子邮件的格式为 service-REPOSITORY_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com， 其中 REPOSITORY_PROJECT_NUMBER 是托管代码库的项目的项目编号。

  3. 用户代管式服务：

    • 向用户代管式服务账号授予自定义 Cloud Build 服务帐号（在代码库项目中）的 Service Account User 角色 (roles/iam.serviceAccountUser)。
    • 向用户代管式服务账号授予运行构建的项目中的 Cloud Build Editor 角色 (roles/cloudbuild.builds.editor) 和 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。

如需了解如何授予 IAM 角色，请参阅授予或撤消单个角色。

创建 build 配置文件

build 配置文件定义 Cloud Build 执行构建任务所需的字段。您可以使用 YAML 语法编写构建配置文件。

您可以在要从中构建的分支中创建 build 配置文件。

如需创建 build 配置文件，请执行以下操作：

  1. 在 Secure Source Manager 网页界面中，选择要连接到 Cloud Build 的代码库。
  2. 选择要使用 Cloud Build 从中构建的分支。

  3. 创建 build 配置文件。如需了解如何 创建 build 配置文件，请按照创建 build 配置文件中的说明操作。

  4. 将更改提交到分支。

创建触发器文件

必须在代码库的默认分支 中创建触发器配置文件。

如需创建触发器配置文件，请执行以下操作：

  1. 在本地代码库或 Secure Source Manager 网页界面中，切换到默认分支 。

  2. 创建一个名为 .cloudbuild/triggers.yaml 的文件。

  3. 在 .cloudbuild/triggers.yaml 文件中配置触发器：

    triggers:
- name: TRIGGER_NAME
  project: PROJECT_ID
  configFilePath: CLOUD_BUILD_CONFIG_PATH
  eventType: EVENT_TYPE
  ignoredGitRefs: IGNORED_GIT_REFS
  includedGitRefs: INCLUDED_GIT_REFS
  serviceAccount: SERVICE_ACCOUNT
  includedFiles: INCLUDED_FILES
  ignoredFiles: IGNORED_FILES
  disabled: DISABLED_BOOL
  substitutions:
    _VARIABLE_NAME: VARIABLE_VALUE
    OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE

    替换以下内容：

    • 将 TRIGGER_NAME 替换为触发器的名称。触发器名称只能包含字母数字字符和连字符，且首尾不能使用连字符。触发器名称的长度必须小于 64 个字符。
    • 将 PROJECT_ID 替换为您在其中 Google Cloud 启用了 Cloud Build 的项目 ID。此字段是可选字段。默认值为 Secure Source Manager 项目。
    • 将 CLOUD_BUILD_CONFIG_PATH 替换为您要用于此触发器的 Cloud Build 配置文件的路径。此字段是可选字段。默认值为 .cloudbuild/cloudbuild.yaml

    • 将 EVENT_TYPE 替换为您要触发构建的事件类型。选项如下：

      • push，用于在推送到指定分支时触发
      • pull_request ，用于在向指定分支发出拉取请求时触发

      此字段是可选字段。默认值为 push。

    • 将 INCLUDED_GIT_REFS 替换为与您要触发构建的 Git 引用匹配的可选 RE2 正则表达式格式。默认值为空。空值表示没有限制。

    • 将 IGNORED_GIT_REFS 替换为使用 RE2 正则表达式格式与您不希望触发构建的 Git 引用匹配的可选正则表达式。默认值为空。空值表示没有限制。系统会在检查 includedGitRefs 字段之前检查 ignoredGitRefs 字段。如需详细了解这些字段，请参阅 触发器文件架构。

    • 将 SERVICE_ACCOUNT 替换为要用于构建的 Cloud Build 服务帐号，格式为 projects/PROJECT_ID/serviceAccounts/ACCOUNT。将 ACCOUNT 替换为 服务帐号的电子邮件地址或唯一 ID。您可以使用默认 Cloud Build 服务账号或用户管理的服务账号。 由于存在 限制，因此无法使用旧版 Cloud Build 服务帐号。

    • 将 INCLUDED_FILES 替换为与您要触发构建的文件匹配的可选 RE2 格式正则表达式。

      如果任何更改的文件与 ignoredFiles 过滤条件字段不匹配，并且更改的文件与 includedFiles 过滤条件字段匹配，则会触发构建。默认值为空。空值表示没有限制。

    • 将 IGNORED_FILES 替换为与您不希望触发构建的文件匹配的可选 RE2 格式正则表达式。

      如果提交中的所有更改的文件都与此过滤条件字段匹配，则不会触发构建。默认值为空。空值表示没有限制。

    • 将 DISABLED_BOOL 替换为 true 以停用触发器，或替换为 false 以启用触发器。此字段是可选字段。默认值为 false。

    • 将 VARIABLE_NAME 替换为您要在触发器文件中引入的变量的名称。

    • 将 VARIABLE_VALUE 替换为变量的值。

    • 将 OVERRIDE_VARIABLE_NAME 替换为 Secure Source Manager 默认替换变量名称。如需了解可用的 默认替换变量，请参阅 触发器文件架构的替换部分。

    • 将 OVERRIDE_VARIABLE_VALUE 替换为您要用于替换默认替换变量的默认值的值。

  4. 将触发器配置文件提交到默认分支。

    提交触发器文件后，Secure Source Manager 会根据触发器文件中的配置触发构建。

    Secure Source Manager 会读取以下类型事件的配置文件和关联的提交 SHA 或 Git 引用：

    • 对于 push 事件，Secure Source Manager 会在推送完成后读取提交 SHA 或 Git 引用。
    • 对于 pull_request 事件，Secure Source Manager 会在拉取请求更改被拉取时读取提交 SHA 或 Git 引用。

查看构建状态

当构建由推送或拉取请求事件触发时，提交和构建状态会显示在 Secure Source Manager 网页界面中。

构建状态的可能值如下：

  • 成功SUCCESS：构建已成功完成。
  • 警告WARNING：尝试构建时出现问题。
  • 失败FAILURE：构建在执行期间失败。

如果您配置了分支保护规则，要求触发器文件中配置的触发器成功完成状态检查，则可以阻止构建失败的提交合并到重要分支中。如需详细了解分支保护 ，请参阅 分支保护概览。

如需查看推送事件的构建状态，请执行以下操作：

  1. 在 Secure Source Manager 网页界面中，前往您的代码库。

    如果最近的推送事件触发了构建，则状态会显示在提交 SHA 旁边。如需查看该状态的详细信息，请点击该状态。

  2. 如需查看之前提交的构建状态，请选择 Commits 以查看提交历史记录，然后点击您要查看详细信息的状态。

如需查看拉取请求事件的构建状态，请执行以下操作：

  1. 在 Secure Source Manager 网页界面中，点击 Pull requests 。

  2. 点击您要查看的拉取请求。

    如果构建是由拉取请求触发的，您将看到一个标题为 **所有检查均成功** 或**部分检查报告了警告** 的部分。

问题排查

如需查找在 连接 Secure Source Manager 时诊断和解决 Cloud Build 错误的方法，请参阅 触发器文件未触发构建。

后续步骤