连接到 GitHub Enterprise 主机

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

准备工作

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

必需的 IAM 权限

如需连接您的 GitHub Enterprise 主机，请授予 Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) 角色分配给您的用户账号。

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

如需使用 gcloud 安装步骤创建连接，请在 Google Cloud 项目中运行以下命令，将 Secret Manager 管理员角色 (roles/secretmanager.admin) 授予 Cloud Build 服务代理：

      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. 在主机详细信息部分中，输入以下信息：

    1. 主机网址：输入连接的主机网址。例如 github.example.com

    2. CA 证书：点击“浏览”上传自签名证书。

    3. 在连接类型下，选择以下选项之一：

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

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

      3. 在 Service Directory service 下，选择服务的位置：

        • 在项目 your-project 中
        • 在其他项目中
        • 手动输入

        1. 如果您选择在其他项目中或手动输入，请输入 以下信息：

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

          • 区域：此字段会预先选择连接所在的区域。指定的区域 必须与您的连接所关联的区域相匹配。

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

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

  8. 点击连接。

    点击连接按钮后，系统会要求您在 GitHub Enterprise 主机中创建 GitHub 应用，并在用户账号或组织中安装该应用。一个 系统将创建来自 GitHub Enterprise 主机的身份验证令牌，并将其存储在此 项目指定为 Secret Manager Secret。你可以通过卸载或 从主机中删除 GitHub 应用。

    Cloud Build 会将所创建应用的 在项目的 Secret Manager 中将 GitHub 应用作为 Secret。 这些数据包括您的私钥和 webhook 密钥。私钥用作访问 API 的身份验证方法 内部 IP 地址webhook 密钥用于验证 从服务器发送到 Cloud Build 的事件。Cloud Build Service Agent 账号 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 用于访问您的 Secret。如需查看您的密钥，请执行以下操作： 请参阅列出 Secret 和查看 Secret 详情。

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

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

gcloud

要使用以下内容将 GitHub Enterprise 主机连接到 Cloud Build： gcloud 命令，请完成以下步骤：

  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. 主页网址：输入 GitHub Enterprise 服务器的网址。
    3. 取消选中过期用户授权令牌对应的复选框。
    4. 在 Webhook 部分中，完成以下步骤：
      • 有效：选中该复选框以激活您的网络预订。
      • 网络钩子网址：输入您的网络钩子网址。例如 https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook。网络钩子网址中的区域必须与区域一致
      • 网络钩子密钥：输入一个随机生成的字符串并记下来。
    5. 在权限部分，指定以下权限：
      • 代码库权限：
        • 检查：读取和写入
        • 内容：读取和写入
        • 问题：只读
        • 元数据 只读
        • 提交状态：只读
        • 拉取请求：只读
    6. 在订阅事件部分，选中以下复选框：
      • 检查运行作业
      • 检查套件
      • 提交评论
      • 发出评论
      • 拉取请求
      • 拉取请求审核备注
      • 推送
      • 代码库
    7. 选中任何账号对应的复选框，以允许任何用户或组织安装您的 GitHub 应用。

  3. 点击创建 GitHub 应用以创建 GitHub 应用。

    点击 Create GitHub app 后，您会被重定向到应用页面。乘坐 记录您的应用 ID 和应用 Slug。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 以编程方式连接 GitHub Enterprise 主机，或者 gcloud。

Terraform

安装 GitHub 应用后，您可以连接 GitHub Enterprise 主机 通过 Google Terraform 提供程序迁移到 Cloud Build。

在以下示例中，代码段将执行以下操作：

  • 配置 Terraform Google 提供程序
  • 创建一个用于存储 GitHub 应用的私钥和 Webhook Secret 的 Secret
  • 向 Cloud Build 服务代理授予访问密钥的必要权限

  • 创建 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 {
        auto {}
    }
}

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 {
        auto {}
    }
}

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 应用的 Webhook Secret 值的 Secret 名称。
  • WEBHOOK_SECRET_VALUE 是 GitHub 应用的 webhook Secret 的值。
  • 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 网址中找到安装 ID。 GitHub 应用 https://github.com/settings/installations/{installation-id}。

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

gcloud

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

  1. 将您的密钥存储在 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 是您为 webhook 密钥创建的字符串。
    • 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 连接。

后续步骤