此页面由 Cloud Translation API 翻译。

连接到 Cloud Build

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

准备工作

所需的角色

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

针对代码库的 Secure Source Manager Repository Writer (roles/securesourcemanager.repoWriter) 角色
Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) 在 Secure Source Manager 实例上

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

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

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

所需的服务账号角色

如需创建 build 并从 Cloud Build 获取 build 状态，请向 Secure Source Manager 服务代理 (service-PROJECT-NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com) 授予以下 Identity and Access Management (IAM) 角色：

您在其中启用了 Cloud Build 的项目的 Cloud Build Editor 角色 (roles/cloudbuild.builds.editor)。
Cloud Build 服务账号或创建 Cloud Build 服务账号的项目中的 Service Account User 角色 (roles/iam.serviceAccountUser)。
如果您启用 Cloud Build 的项目与启用 Secure Source Manager 的项目不同，请在 Cloud Build 项目中授予 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。
如果构建在工作器池中运行，请向 Secure Source Manager 服务账号授予 Cloud Build 项目的 Cloud Build WorkerPool User 角色 (roles/cloudbuild.workerPoolUser)。

如需让 Cloud Build 从 Secure Source Manager 代码库中读取内容，请向 Cloud Build 服务账号授予以下 IAM 角色：

Secure Source Manager 实例的 Secure Source Manager Instance Accessor 角色 (roles/securesourcemanager.instanceAccessor)。
您要连接到 Cloud Build 的 Secure Source Manager 代码库的 Secure Source Manager Repository Reader 角色。

根据您的使用情形，Cloud Build 服务账号可能需要其他 IAM 角色才能执行构建，例如：

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

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

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

创建构建配置文件

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

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

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

在 Secure Source Manager 网页界面中，选择要连接到 Cloud Build 的代码库。
选择要使用 Cloud Build 构建的分支。
创建 build 配置文件。如需了解如何创建 build 配置文件，请按照创建 build 配置文件中的说明操作。
将更改提交到分支。

创建触发器文件

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

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

在本地代码库或 Secure Source Manager 网页界面中，切换到默认分支。
创建一个名为 .cloudbuild/triggers.yaml 的文件。
在 .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 替换为您要触发 build 的事件类型。选项如下：
  - push 在推送到指定分支时触发
  - pull_request：在收到针对指定分支的拉取请求时触发
  此字段是可选字段。默认值为 push。
- INCLUDED_GIT_REFS，其中包含与您要触发构建的 Git 参考相匹配的可选 RE2 正则表达式格式。默认值为空。空值表示没有限制。
- IGNORED_GIT_REFS，其中包含一个可选的正则表达式，该表达式使用 RE2 正则表达式格式，用于匹配您不希望触发 build 的 Git 参考。默认值为空。空值表示没有限制。系统会在检查 includedGitRefs 字段之前检查 ignoredGitRefs 字段。如需详细了解这些字段，请参阅触发器文件架构。
- SERVICE_ACCOUNT，其中包含用于构建的 Cloud Build 服务账号，格式为 projects/PROJECT_ID/serviceAccounts/ACCOUNT。将 ACCOUNT 替换为服务账号的电子邮件地址或唯一 ID。最佳实践是配置用户指定的服务账号。由于旧版 Cloud Build 服务账号存在限制，因此无法使用。
- INCLUDED_FILES 替换为可选的 RE2 格式正则表达式，用于匹配您希望触发构建的文件。
  
  如果任何更改的文件与 ignoredFiles 过滤条件字段不匹配，但与 includedFiles 过滤条件字段匹配，则会触发构建。默认值为空。空值表示没有限制。
- IGNORED_FILES，其中包含一个可选的 RE2 格式正则表达式，用于匹配您不希望触发构建的文件。
  
  如果提交中的所有已更改文件都与此过滤条件字段匹配，则不会触发 build。默认值为空。空值表示没有限制。
- 将 DISABLED_BOOL 替换为 true 以停用触发器，或替换为 false 以启用触发器。此字段是可选字段。默认值为 false。
- 将 VARIABLE_NAME 替换为要在触发器文件中引入的变量的名称。
- 将 VARIABLE_VALUE 替换为变量的值。
- 将 OVERRIDE_VARIABLE_NAME 替换为 Secure Source Manager 默认替换变量名称。如需了解可用的默认替换变量，请参阅触发器文件架构的“替换”部分。
- OVERRIDE_VARIABLE_VALUE 替换为要用于替换默认替换变量的默认值的值。
将触发器配置文件提交到默认分支。

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

Secure Source Manager 会读取以下类型事件的配置文件和关联的提交 SHA 或 Git ref：
- 对于 push 事件，Secure Source Manager 会在推送完成后读取提交 SHA 或 Git ref。
- 对于 pull_request 事件，当从拉取请求中拉取更改时，Secure Source Manager 将读取提交 SHA 或 Git ref。

查看 build 状态

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

build 状态的可能值如下：

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

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

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

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

如果最新的推送事件触发了 build，则状态会显示在提交 SHA 旁边。如需查看相应状态的详细信息，请点击该状态。
如需查看之前提交的构建状态，请选择提交以查看提交历史记录，然后点击要查看详细信息的状态。

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

在 Secure Source Manager 网页界面中，点击 Pull request。
点击要查看的拉取请求。

如果 build 是由 pull 请求触发的，您会看到一个标题为所有检查均成功或部分检查报告了警告的部分。

问题排查

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

后续步骤

了解如何在 Cloud Build 中查看构建结果。
了解如何排查构建错误。

连接到 Cloud Build 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。