从 GitHub Enterprise 构建代码库

借助 Cloud Build,您可以在 GitHub Enterprise 实例上创建触发器。本页面介绍如何使用 GitHub Enterprise 触发器调用构建,以响应来自 GitHub Enterprise 实例的提交或拉取请求。

准备工作

  • 启用 Cloud Build and Secret Manager API。

    启用 API

  1. 为本地主机启用专用 Google 访问通道,以确保您的 GitHub Enterprise 实例可以访问 Google Cloud API 和服务

  2. 将您的本地网络与 Google Cloud 对等互连并设置 Virtual Private Cloud (VPC) 网络。如需了解详情,请参阅与 VPC 网络对等互连

  3. 使用专用池运行构建。设置项目的环境并在 VPC 上创建新的专用工作器池(如果您尚未这样做)。如需了解如何使用专用工作器池运行构建,请参阅在专用池中运行构建

必需的 IAM 权限

如需连接您的 GitHub Enterprise 主机,您需要向您的用户帐号添加 Cloud Build Editor (roles/cloudbuild.builds.editor) 角色和 Cloud Build Integrations Owner (cloudbuild.integrations.owner) 角色:

如需向您的用户帐号添加所需的角色,请参阅配置对 Cloud Build 资源的访问权限。如需详细了解与 Cloud Build 关联的 IAM 角色,请参阅 IAM 角色和权限

与 VPC 网络对等互连

如果您的 GitHub Enterprise 实例托管在本地环境中,并且无法通过公共互联网连接访问,您需要将本地网络与 Google Cloud 对等互连并设置 VPC 网络。

  1. 启用 Service Networking API
  2. 创建新的 VPC 网络选择现有的 VPC 网络。注意:您必须将 VPC 网络配置为可访问本地 GitHub Enterprise 实例。
  3. 在 VPC 网络中分配已命名的 IP 范围。如需将 VPC 网络与 Cloud Build 专用池配合使用,您的前缀长度必须为 /23 或更低,例如 /22/21 等。
  4. 在 VPC 网络和 Google Cloud 之间建立 VPC 网络对等互连连接。如需了解详情,请参阅创建专用连接
  5. 如果您为 GitHub Enterprise 实例配置了 DNS,则需要手动将您的 DNS 区域与我们的服务提供商对等互连。如需了解详情,请参阅与服务提供方共享专用 DNS 区域
  6. [可选] 如果您不希望对等互连 Cloud 项目的网络,则可以设置共享 VPC,并让 Cloud 项目使用该网络(如果项目属于某个组织分)。您仍需将共享 VPC 与 Service Networking API 对等互连。

创建 Cloud Build GitHub 应用

您需要在 GitHub Enterprise 实例上创建一个 GitHub 应用。该应用会将网络钩子事件发送到 Cloud Build 端点。收到事件后,如果事件对应于 Cloud Build GitHub 触发器,Cloud Build 将验证载荷并执行构建。您需要为在要配置 GitHub Enterprise 触发器的代码库上安装应用。

本部分介绍如何创建 GitHub 应用:

  1. 登录您的 GitHub Enterprise 实例。
  2. 确保您已安装最新版本的 GitHub Enterprise。

    在某些版本的 GitHub Enterprise 中,您可能需要停用 SameSite Cookie,才能在 Chrome 浏览器中完成以下步骤。如果您的 GitHub Enterprise 版本低于 2.21.3,则需要停用 SameSite Cookie:

    1. 转到 chrome://flags/
    2. 在过滤栏中输入 samesite
    3. 确保 SameSite by default cookies 已停用。

      已停用 SameSite 的屏幕截图

    4. 重新启动浏览器。

  3. 打开 Cloud Build 的管理代码库页面:

    打开“管理代码库”页面

  4. 点击连接主机

    您将看到 Connect host 面板,它会提示您创建主机连接以将 GitHub Enterprise 代码库连接到 Cloud Build。

  5. 主机网址部分中,输入 GitHub Enterprise 实例的网址。例如 ghe.example.com

  6. API 密钥部分,点击生成以生成 API 密钥;如果您已经有 API 密钥,则输入 API 密钥。

    如果要手动创建 API 密钥,请完成以下步骤:

    要获取 API 密钥,请执行以下操作:

    1. 在 Cloud Console 中打开凭据页面。

      打开“凭据”页面

    2. 点击创建凭据

    3. 点击 API 密钥

      您将看到一个弹出式窗口,其中包含创建的 API 密钥。

    4. 点击限制密钥

    5. API 限制下,从下拉菜单中选择 Cloud Build API

    6. 点击保存

  7. [可选] 在组织部分中,输入将为其创建 GitHub 应用的组织。如果将此部分留空,则将在当前用户帐号下创建应用。

  8. [可选] 在 CA 证书部分中,点击浏览以上传您的自签名证书。您的证书大小不得超过 10 kB,并且应采用 PEM 格式(.pem.cer.crt)。如果此部分留空,则将使用一组默认证书

  9. [可选] 在网络部分,输入您的网络项目的名称以及网络名称(如果您的 GitHub 企业实例托管在本地,并且您已将网络对等互连到 Google Cloud。

  10. 点击连接主机

    如果您的 GitHub Enterprise 实例位于对等互连网络上,则主机连接过程可能需要几分钟才能完成。

  11. 如果要将代码库连接到 Cloud Build,请点击连接代码库。否则,请点击完成

  12. 连接主机后,系统会显示一个弹出式窗口,提示您输入 GitHub Enterprise 应用的名称。在输入应用名称之前,系统可能会要求您登录。如果您使用的是 Google Chrome 浏览器,弹出式窗口可能会要求您手动输入 GitHub Enterprise 应用的相关信息。

  13. 登录后,输入 GitHub 应用的名称。

  14. 点击 Create GitHub App

    您刚刚在 GitHub Enterprise 实例上创建了一个 GitHub 应用。Cloud Build 会自动将您的凭据存储在 Secret Manager 中,并将主机连接到您的 Cloud 项目。在 API 中,此连接表示为 GitHubEnterpriseConfig 资源,或者 Cloud Build 与您的 GitHub Enterprise 服务器之间的关联。

    您的主机现已成功连接。如果要将代码库连接到 Cloud Build,您可以点击连接代码库

连接 GitHub Enterprise 代码库

本部分介绍如何将 Cloud 项目映射到您在上一部分中创建的 GitHub 应用。

控制台

  1. 打开 Google Cloud Console 中的触发器页面。

    打开“触发器”页面

  2. 点击关联代码库

  3. 选择来源下,点击 GitHub Enterprise

  4. 从下拉菜单中选择您的主机连接(GitHub Enterprise Config)。

  5. 点击继续

  6. 为应用授权。

  7. 选择代码库下,从下拉菜单中选择您的 GitHub 帐号代码库

API

要在相应的 GitHub 用户帐号或组织中安装 GitHub 应用,并将其连接到 Cloud Build 项目,请执行以下操作:

  1. 导航至与上一部分中创建的 GitHub 应用关联的网址:

       https://host-url/organizations/org-name/settings/apps/app-name/
    

    其中:

    • host-url 是您的 GitHub Enterprise 实例的主机网址。
    • org-name 是您在其中创建项目的组织的名称。
    • app-name 是您的 GitHub 应用的名称。
  2. 通过该网址在您的用户帐号或组织中安装应用。

    安装应用后,记下与该应用关联的安装 ID,您可以在网址中找到安装 ID。

  3. 使用以下内容创建 JSON 文件:

    {
     "Id": installation-id,
     "project_id": "project-id",
     "repository_setting_list": {
            "repository_settings": {
            "owner": "owner",
            "name": "repo-name",
          },
          "repository_settings": {
            "owner": "owner",
            "name": "repo-name-additional"
          },
         …
     },
        "enterprise_config_resource_name": "projects/project-number/githubEnterpriseConfigs/id"
    }
    

    其中:

    • installation-id 是 GitHub 应用的安装 ID。注意:此值是整数,并且不需要引号。
    • project-id 是与安装关联的 Cloud 项目。
    • owner 是 GitHub 代码库的所有者。
    • repo-name 是 GitHub 代码库的名称。
    • [可选] repo-name-additional 是另一个 GitHub 代码库的名称。
    • project-number 是 Cloud 项目的编号。
    • id 是 GitHubEnterpriseConfig 的 ID。
  4. 在终端中输入以下 curl 命令,其中 project-id 是 Cloud 项目 ID:

     curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/installations -d @installation.json
    

您现在可以在触发器页面的非活动标签页下查看与安装关联的代码库。

为 GitHub Enterprise 安装创建 GitHub 触发器

本部分介绍如何创建触发器并将其与 GitHub Enterprise 安装关联。 如果要在本地环境中使用 GitHub Enterprise 触发器,请参阅从 GitHub Enterprise 在本地环境中构建代码库,了解更多说明。

控制台

如需了解如何使用 GitHub 触发器创建触发器,请参阅创建 GitHub 触发器

API

以下 JSON 模板展示了如何通过命令行创建触发器:

  {
      "filename": "cloudbuild.yaml",
      "name": "curl-trigger",
      "description": "curl trigger",
      "github": {
          "push": {
              "branch": ".*",
          },
          "owner": "owner",
          "name": "repo-name",
      "enterprise_config_resource_name": "projects/project-number/githubEnterpriseConfigs/id"
      }
  }

其中:

  • owner 是 GitHub 代码库的所有者。
  • repo-name 是 GitHub 代码库的名称。
  • project-number 是 Cloud 项目的编号。
  • id 是您的 GitHubEnterpriseConfig 的 ID。

在终端中输入以下 curl 命令,其中 project-id 是 Cloud 项目 ID:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/project-id/triggers -d @trigger.json

您的触发器现已创建。

从 GitHub Enterprise 在本地环境中构建代码库

本部分介绍如何使用 GitHub Enterprise 触发器在 GitHub Enterprise 实例上的专用池中构建。

要创建在本地环境中构建的 GitHub Enterprise 触发器,请执行以下操作:

  1. 启用为本地主机启用专用 Google 访问通道,以确保您的 GitHub 企业版实例可以访问 Google Cloud API 和服务

  2. 将您的本地网络与 Google Cloud 对等互连并设置 Virtual Private Cloud (VPC) 网络。如需了解详情,请参阅与 VPC 网络对等互连

  3. 创建 GitHub Enterprise 触发器以构建托管在 GitHub Enterprise 实例上的代码库。

现在,您的 GitHub Enterprise 触发器将根据您的配置自动在 GitHub Enterprise 实例上调用构建。

后续步骤