从 GitHub 构建代码库

GitHub 触发器可让您基于 Git 推送和拉取请求自动构建，并在 GitHub 和 Google Cloud Console 上查看构建结果。此外，GitHub 触发器支持现有 GitHub 触发器支持的所有功能，并使用 Cloud Build GitHub 应用配置并向 GitHub 进行身份验证。

本页面介绍了如何使用 Cloud Build GitHub 应用创建 GitHub 触发器并在 GitHub 上进行构建。

准备工作

• 启用 Cloud Build API。

  启用 API

• 按照连接到 GitHub 代码库中的说明安装 Cloud Build GitHub 应用。

创建 GitHub 触发器

控制台

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

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

   打开“触发器”页面

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

3. 点击打开。

4. 点击创建触发器。

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

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

   • 区域：选择触发器的区域。

     • 如果选择全球作为区域，则 Cloud Build 会使用默认池运行构建。
     • 如果您选择非全球区域，并且与触发器关联的构建配置文件指定专用池，则 Cloud Build 会使用专用池运行构建。在这种情况下，您在触发器中指定的区域必须与您创建专用池的区域一致。
     • 如果您选择非全球区域，并且与触发器关联的构建配置文件没有指定专用池，则 Cloud Build 会使用默认池在触发器所在的区域中运行构建。

   • 说明（可选）：输入触发器的说明。

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

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

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

     • 拉取请求（不支持 Cloud Source Repositories）：设置触发器，以便基于针对拉取请求进行的提交启动构建。

       注意：当您关闭与构建相关联的拉取请求时，系统会取消 GitHub 应用拉取请求触发器启动的正在运行的构建。合并拉取请求时，系统不会取消正在运行的构建和尚未启动的构建。

   • 来源：选择代码库以及相应的分支或标记来监视事件。

     注意：您的代码库所在的区域必须与触发器的区域一致。

     • 代码库：从可用代码库列表中，选择所需的代码库。如需关联新的代码库，请参阅关联其他代码库。

     • 分支或标记：指定要匹配分支或标记值的正则表达式。如需了解可接受的正则表达式语法，请参阅 RE2 语法。

     • 评论控制：如果您选择了拉取请求（仅限 GitHub 应用）作为事件，请选择以下选项之一来控制构建是否将由触发器自动执行：

       警告：对代码库具有读取权限的任何用户都可以提交拉取请求，该请求可能会执行包含拉取请求源代码更改的构建。如需停用此行为，我们建议您在对公共代码库发出拉取请求时使用手动批准来控制构建。如需详细了解触发器的构建时权限，请参阅构建触发器和 Cloud Build 服务帐号。

       • 必需（所有者和协作者除外）：代码库所有者或协作者创建或更新拉取请求后，触发器会自动执行构建。如果外部贡献者发起操作，则只有在所有者或协作者对拉取请求中的 /gcbrun 添加注释之后，触发器才会执行构建。

       • 必需：任何贡献者创建或更新拉取请求时，只有在所有者或协作者对拉取请求发出 /gcbrun 注释后，系统才会执行构建。每当对拉取请求进行更改时，系统都会执行构建。

       • 不需要：任何贡献者创建或更新拉取请求后，触发器将自动执行构建。

   • 包含的文件（可选）：如果更改影响至少一个文件，则会调用构建。

   • 忽略的文件（可选）：如果更改只影响被忽略的文件，则不会调用构建。

     注意：只有在您选择了推送到分支作为事件的情况下，才能指定包含的文件和忽略的文件。如需详细了解包含的文件和忽略的文件，请参阅创建构建触发器下的控制台标签页。

   • 配置：选择位于远程代码库中的构建配置文件，或创建要用于构建的内嵌构建配置文件。

     • 类型：选择要用于构建的配置类型。
       • 自动检测：如果您的代码库中有 cloudbuild.yaml 或 Dockerfile，Cloud Build 会自动检测您的配置类型。
       • Cloud Build 配置文件（yaml 或 json）：为您的配置使用构建配置文件。
       • Dockerfile：为您的配置使用 Dockerfile。
       • Buildpack：为您的配置使用 buildpack。

     • 位置：为您的配置指定位置。

       • 代码库：如果您的配置文件位于远程代码库中，请提供构建配置文件或 Dockerfile 目录的位置和生成的映像的名称。如果您的配置是 Dockerfile，则还可以选择提供构建的超时时间。提供了 Dockerfile 和映像名称后，您会看到构建将执行的 docker build 命令的预览。
       • 内嵌：如果您选择了 Cloud Build 配置文件（yaml 或 json）作为配置选项，则可以指定内嵌构建配置。点击打开编辑器，使用 YAML 或 JSON 语法在 Google Cloud Console 中编写构建配置文件。点击完成以保存您的构建配置。
       注意：内嵌构建配置支持不适用于 Dockerfile。

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

   • Approval（可选）：选中相应复选框，要求在执行构建之前获得批准。如需详细了解审批，请参阅基于审批的 build。

   • Build logs（可选）：勾选相应复选框以将构建日志发送到 GitHub。如需了解如何查看构建日志，请参阅查看构建日志。

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

     注意：只有为触发器指定的服务帐号将用于通过触发器执行的构建。如果您在构建配置中指定了服务帐号，则在使用触发器时，该服务帐号会在构建执行期间被忽略。

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

如需使用 gcloud 命令创建 GitHub 应用触发器，请参阅创建构建触发器的 gcloud 命令。

gcloud

如需使用 gcloud 命令创建 GitHub 触发器，请运行以下命令：

gcloud beta builds triggers create github \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --include-logs-with-status

其中：

• REPO_NAME 是代码库的名称。
• REPO_OWNER 是代码库所有者的用户名。
• BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
• TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
• BUILD_CONFIG_FILE 是构建配置文件的路径。
• [可选] --include-logs-with-status 是一个标志，您可以指定为显示代码库的构建日志。来自 GitHub 和 GitHub Enterprise 代码库的构建支持此标志。如需了解如何查看构建日志，请参阅查看构建日志。

注意：只有在使用 gcloud 创建 GitHub 或 GitHub Enterprise 触发器时，才能使用 --include-logs-with-status 标志。Cloud Build 目前不支持使用 Google Cloud Console 创建触发器的功能。如需了解如何更新触发器以包含或移除标志，请参阅更新构建触发器。

构建和查看更改

如需使用 GitHub 触发器进行构建，您需要推送更改并将其提交到关联的源代码库，或在拉取请求上配置构建。检查更改后，Cloud Build 将构建代码。

如要在 GitHub 上查看构建更改，请转到代码库中的检查标签页。

您将看到 Cloud Build 已构建您的更改。您还将看到其他构建详情，例如构建代码所花费的时间和构建 ID。

如需在 Cloud Build 中查看构建更改，请点击在 Google Cloud Build 中查看更多详情。系统会打开 Google Cloud Console 中的构建详情页面，您可以在其中查看状态、日志和构建步骤等构建信息。

基于 GitHub 的不同类型触发器

如果您的源代码位于 GitHub 中，Cloud Build 提供了两种自动执行构建的方式。本部分介绍并比较两种基于 GitHub 的触发器。

• GitHub 旧版触发器：当您创建 GitHub 旧版触发器时，Cloud Build 会镜像您的 Cloud Source Repositories 中的 GitHub 代码库，并使用镜像代码库执行其所有操作。您可以使用 Google Cloud Console 创建和管理 GitHub 触发器。

  注意：如果您使用的是 GitHub 旧版触发器，则需要通过 GitHub 向个别组织授予访问权限来使用 GitHub 旧版触发器。

• GitHub 触发器：这种触发器使用 Cloud Build GitHub 应用配置并向 GitHub 验证身份。GitHub 触发器允许您自动启动 Git 推送和拉取请求的构建，并在 GitHub 和 Google Cloud Console 上查看构建结果。如本页面所述，您可以使用 Google Cloud Console 或 Cloud Build API 创建和管理 GitHub 触发器。

• GitHub Enterprise 触发器：这种触发器允许您调用构建以响应 GitHub Enterprise 实例上的提交或拉取请求。您可以使用 Google Cloud Console 或 Cloud Build API 从 GitHub Enterprise 构建代码库。

下表比较了 GitHub 旧版触发器、GitHub 触发器和 GitHub Enterprise 触发器：

特征	GitHub 旧版触发器	GitHub 触发器	GitHub Enterprise 触发器
基于推送到源代码的请求执行构建	是	是	是
对拉取请求执行构建	否	是	是
使用 Google Cloud Console 创建触发器	是	是	是
使用 Cloud Build API 创建触发器	否	是	是
使用 Cloud Build GitHub 应用创建触发器	否	是	是
在 Google Cloud Console 上查看构建状态	是	是	是
在 GitHub 上查看构建状态	否	是	是

数据共享

GitHub 触发器将数据发送到 Cloud Build GitHub 应用。发送到应用的数据有助于您按名称识别触发器，并在 GitHub 上查看构建结果。

以下数据目前在 Google Cloud 和 GitHub 应用之间共享：

• Cloud 项目 ID
• 触发器名称
• 构建日志

如果您是在 2020 年 8 月之前创建的触发器，则您的项目可能未启用数据共享功能。如需为项目中的所有 GitHub 触发器启用数据共享，请点击 Cloud Build 数据共享标签页上的启用。

如果为 GitHub 代码库启用了必需的状态检查，则启用数据共享可能会暂时中断状态检查。您可以通过以下方式调整状态检查配置以查找触发器名称：

• 在 GitHub 代码库中停用任何特定于 Cloud Build 的必需检查
• 确保在 Cloud Build 中启用数据共享功能
• 在 Cloud Build 中执行一项新构建，将状态发布到您的代码库
• 重新启用必需的状态检查，选择触发器名称

注意：为项目启用数据共享不可撤消。

后续步骤

• 了解如何创建和管理构建触发器。