连接到 GitHub Enterprise 主机

本页面介绍了如何将 GitHub Enterprise 主机连接到 Cloud Build。

准备工作

  • 启用 Cloud Build and Secret Manager API。

    启用 API

必需的 IAM 权限

如需连接 GitHub Enterprise 主机,请向您的用户帐号授予 Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) 角色。

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

如需使用 gcloud 安装步骤创建连接,请在 Google Cloud 项目中运行以下命令,将 Secret Manager Admin 角色 (roles/secretmanager.admin) 授予 Cloud Build Service Agent:

      PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
      CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
       gcloud projects add-iam-policy-binding ${PROJECT_ID} \
         --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
         --role="roles/secretmanager.admin"

如果您的 GitHub Enterprise 实例托管在专用网络中,请参阅在专用网络中从 GitHub Enterprise 构建代码库,了解主机连接之前所需的其他 IAM 角色。

连接到 GitHub Enterprise 主机

控制台

如需将 GitHub Enterprise 主机连接到 Cloud Build,请执行以下操作:

  1. 打开 Google Cloud 控制台中的制品库页面。

    打开“代码库”页面

    您将看到代码库页面。

  2. 在顶部栏的项目选择器中,选择您的 Google Cloud 项目。

  3. 在页面顶部,选择第 2 代标签页。

  4. 点击创建主机连接,将新主机连接到 Cloud Build。

  5. 在左侧面板中,选择 GitHub Enterprise 作为来源提供商。

  6. Configure Connection 部分,输入以下信息:

    1. 区域:选择连接的区域。

    2. 名称:输入连接的名称。

  7. Host details(主机详情)部分,输入以下信息:

    1. Host 网址(主机网址):输入连接的主机网址。例如 github.example.com

    2. CA 证书:点击“浏览”可上传您的自签名证书。

    3. 连接类型下,选择以下选项之一:

      1. 公共互联网:如果您的实例可通过公共互联网访问,请选择此选项。

      2. 专用网络访问:如果您的实例托管在专用网络中,请选择此选项。

      3. Service Directory 服务下,选择服务的位置:

        • 在项目 your-project
        • 在其他项目中
        • 手动输入
        1. 如果您选择在其他项目中手动输入,请输入以下信息:

          • 项目:从下拉菜单中选择您的 Google Cloud 项目 ID。

          • 区域:此字段会预先选择您的连接所在的区域。为您的服务指定的区域必须与您的连接关联的区域一致。

        2. 命名空间:选择服务的命名空间。

        3. Service:选择命名空间中的服务名称。

  8. 点击连接

    点击连接按钮后,系统会要求您在 GitHub Enterprise 主机中创建 GitHub 应用,并在用户帐号或组织中安装该应用。系统将创建来自 GitHub Enterprise 主机的身份验证令牌,并将其作为 Secret Manager 密钥存储在此项目中。您可以随时从主机上卸载或删除 GitHub 应用来撤消访问权限。

    Cloud Build 将创建的 GitHub 应用的身份验证数据作为 Secret 存储在项目的 Secret Manager 中。此数据包括您的私钥和网络钩子密钥。私钥用作访问 Enterprise Server 的 API 的身份验证方法。网络钩子密钥用于验证从服务器发送到 Cloud Build 的事件。Cloud Build 服务代理帐号 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 用于访问您的密钥。如需查看您的 Secret,请参阅列出 Secret 和查看 Secret 详情

    为 Cloud Build GitHub 应用授权后,您将被重定向到 Cloud Build 代码库页面。

现在,您已成功创建 GitHub Enterprise 连接。

gcloud

如需使用 gcloud 命令将 GitHub Enterprise 主机连接到 Cloud Build,请完成以下步骤:

  1. 输入以下命令以创建 GitHub Enterprise 连接:

    gcloud builds connections create github-enterprise CONNECTION_NAME \
      --host-uri=HOST_URI --region=REGION
    

    其中:

    • CONNECTION_NAME 是您的连接的名称。
    • HOST_URI 是您的 GitHub Enterprise 实例的 URI。例如 https://mmy-ghe-server.net
    • REGION 是您的连接的区域

    如果您的 GitHub Enterprise 实例位于专用网络中,请指定 Service Directory 资源。您还可以指定自己的 CA 证书。

    --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
    --ssl-ca-file=SSL_CA_FILEPATH
    

    其中:

    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • REGION 是您的连接的区域
    • NAMESPACE 是服务的命名空间。
    • SERVICE_NAME 是命名空间中服务的名称。
    • SSL_CA_FILEPATH 是 CA 证书的文件路径。

    运行 gcloud builds connections... 命令后,您将收到一个用于安装 Cloud Build GitHub 应用的链接。

  2. 按照上一步中返回的链接,在您的企业服务器上创建并安装 Cloud Build GitHub 应用。

  3. 输入以下命令以验证连接:

    gcloud builds connections describe CONNECTION_NAME --region=REGION
    

    其中:

    • CONNECTION_NAME 是您的连接的名称。
    • REGION 是您的连接的区域

    如果 installationState 字段设置为 COMPLETE,则表示您已成功安装连接。否则,installationState 字段会提供相关额外步骤的链接。

现在,您已成功创建 GitHub Enterprise 连接。

以编程方式连接到 GitHub Enterprise 主机

如需以程序化方式将 GitHub Enterprise 主机连接到 Cloud Build,您必须完成以下步骤来安装 GitHub 应用:

  1. 注册一个新的 GitHub 应用。例如,您可以在 https://my-ghe-server.net/settings/apps/new 上注册一个新的 GitHub 应用。

  2. 填写该页面上的字段:

    1. GitHub App Name:输入应用的名称。
    2. Homepage 网址(主页网址):输入您的 GitHub Enterprise 服务器的网址。
    3. 取消选中用户授权令牌过期对应的复选框。
    4. 网络钩子部分,完成以下步骤:
      • 有效:选中该复选框即可激活您的 Webook。
      • 网络钩子网址:输入您的网络钩子网址。例如 https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook。网络钩子网址中的区域必须与连接的区域一致。
      • 网络钩子密钥:输入随机生成的字符串并记下该字符串。
    5. 权限部分,指定以下权限:
      • 代码库权限
        • 检查:读取和写入
        • 内容:读取和写入
        • 问题:只读
        • 元数据(只读)
        • 提交状态:只读
        • 拉取请求:只读
    6. 订阅活动部分,勾选以下复选框:
      • 检查运行
      • 检查套件
      • 提交评论
      • 问题备注
      • 拉取请求
      • 拉取请求审核备注
      • 推送
      • 代码库
    7. 勾选任何帐号对应的复选框,以允许任何用户或组织安装您的 GitHub 应用。
  3. 点击创建 GitHub 应用以创建 GitHub 应用。

    点击创建 GitHub 应用后,您将被重定向到您的应用页面。记下您的应用 ID 和应用标识符。您可在页面网址的最后一部分找到 App slug。例如 https://my-ghe-server.net/settings/apps/{app-slug}

  4. 私钥部分,点击生成私钥

    将下载的文件存储在安全的位置。

  5. 在左侧窗格中,选择安装应用

    选择要安装该应用的用户或组织。安装应用后,请记下安装 ID。安装 ID 可在页面网址的最后一段找到。例如 https://my-ghe-server.net/settings/installations/{installation-id}

安装 GitHub 应用后,请完成以下步骤,使用 Terraform 或 gcloud 以编程方式连接 GitHub Enterprise 主机。

Terraform

安装 GitHub 应用后,您可以使用 Google Terraform 提供程序将 GitHub Enterprise 主机连接到 Cloud Build。

在以下示例中,代码段会执行以下操作:

  • 配置 Terraform Google 提供方
  • 创建一个密钥来存储 GitHub 应用的私钥和网络钩子密钥
  • 向 Cloud Build Service Agent 授予访问密钥的必要权限
  • 创建 GitHub Enterprise 连接

    // Configure the terraform google provider
    terraform {
      required_providers {
        google = {}
      }
    }
    
    // create Secrets and grant permissions to the Service Agent
    resource "google_secret_manager_secret" "private-key-secret" {
        project = "PROJECT_ID"
        secret_id = "PRIVATE_KEY_SECRET"
    
        replication {
            automatic = true
        }
    }
    
    resource "google_secret_manager_secret_version" "private-key-secret-version" {
        secret = google_secret_manager_secret.private-key-secret.id
        secret_data = file("private-key.pem")
    }
    
    resource "google_secret_manager_secret" "webhook-secret-secret" {
        project = "PROJECT_ID"
        secret_id = "WEBHOOK_SECRET"
    
        replication {
            automatic = true
        }
    }
    
    resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
        secret = google_secret_manager_secret.webhook-secret-secret.id
        secret_data = "WEBHOOK_SECRET_VALUE"
    }
    
    data "google_iam_policy" "serviceagent-secretAccessor" {
        binding {
            role = "roles/secretmanager.secretAccessor"
            members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
        }
    }
    
    resource "google_secret_manager_secret_iam_policy" "policy-pk" {
      project = google_secret_manager_secret.private-key-secret.project
      secret_id = google_secret_manager_secret.private-key-secret.secret_id
      policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
    }
    
    resource "google_secret_manager_secret_iam_policy" "policy-whs" {
      project = google_secret_manager_secret.webhook-secret-secret.project
      secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
      policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
    }
    
    // create the connection and add the repository resource ---
    resource "google_cloudbuildv2_connection" "my-connection" {
        project = "PROJECT_ID"
        location = "REGION"
        name = "CONNECTION_NAME"
    
        github_enterprise_config {
            host_uri = "URI"
            private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
            webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
            app_id = "APP_ID"
            app_slug = "APP_SLUG"
            app_installation_id = INSTALLATION_ID
        }
    
        depends_on = [
            google_secret_manager_secret_iam_policy.policy-pk,
            google_secret_manager_secret_iam_policy.policy-whs
        ]
    }
    

其中:

  • PROJECT_ID 是您的 Google Cloud 项目 ID。
  • PRIVATE_KEY_SECRET 是包含 GitHub 应用私钥的 Secret。
  • WEBHOOK_SECRET 是包含 GitHub 应用的网络钩子密钥值的 Secret 名称。
  • WEBHOOK_SECRET_VALUE 是 GitHub 应用的网络钩子密钥的值。
  • REGION 是您的连接的区域
  • CONNECTION_NAME 是您的 GitHub 连接的名称。
  • URI 是您的连接的 URI。例如 https://my-github-enterprise-server.net
  • APP_ID 是您的 GitHub 应用的 ID。
  • APP_SLUG 是应用 slug。例如 https://github.com/settings/apps/{app-slug}
  • INSTALLATION_ID 是您的 GitHub 应用的安装 ID。您可以在 Cloud Build GitHub 应用的网址 https://github.com/settings/installations/{installation-id} 中找到安装 ID。

现在,您已成功创建 GitHub Enterprise 连接。

gcloud

安装 GitHub 应用后,请完成以下步骤,使用 gcloud 以编程方式连接 GitHub Enterprise 主机:

  1. 将您的 Secret 存储在 Secret Manager 中:

    echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
    # creating secret from the downloaded private key:
    gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE
    

    其中:

    • WEBHOOK_SECRET 是您为网络钩子密钥创建的字符串。
    • PRIVATE_KEY_FILE 是您生成的私钥的文件路径。
  2. 向 Cloud Build 服务代理授予访问权限以访问您的密钥:

    PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
    CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
    gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
      --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
      --role="roles/secretmanager.secretAccessor"
    gcloud secrets add-iam-policy-binding mygheapp-private-key \
      --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
      --role="roles/secretmanager.secretAccessor"
    

    其中:

    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • CLOUD_BUILD_SERVICE_AGENT 是您按产品划分的帐号。
  3. 创建 GitHub Enterprise 连接:

    gcloud builds connections create github-enterprise CONNECTION_NAME \
      --host-uri=HOST_URI \
      --app-id=APP_ID \
      --app-slug=APP_SLUG \
      --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
      --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
      --app-installation-id=INSTALLATION_ID \
      --region=REGION
    

    其中:

    • CONNECTION_NAME 是您的连接的名称。
    • HOST_URI 是您的 GitHub Enterprise 实例的 URI。例如 https://mmy-ghe-server.net
    • APP_ID 是您的 GitHub 应用的 ID。
    • APP_SLUG 是应用 slug。例如 https://my-ghe-server.net/settings/apps/app-slug
    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • INSTALLATION_ID 是您的 GitHub 应用的安装 ID。例如 https://my-ghe-server.net/settings/installations/installation-id
    • REGION 是您的连接的区域

    如果您的 GitHub Enterprise 实例位于专用网络中,请指定 Service Directory 资源。您还可以指定自己的 CA 证书。

      --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
      --ssl-ca-file=SSL_CA_FILEPATH
    

    其中:

    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • REGION 是您的连接的区域
    • NAMESPACE 是服务的命名空间。
    • SERVICE_NAME 是命名空间中服务的名称。
    • SSL_CA_FILEPATH 是 CA 证书的文件路径。

现在,您已成功创建 GitHub Enterprise 连接。

后续步骤