连接到 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. 在配置连接部分中，输入以下信息：

    1. 区域：为您的连接选择区域。

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

  7. 在主机详细信息部分中，输入以下信息：

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

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

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

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

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

      3. 在服务目录服务下，选择服务的位置：

        • 在项目 your-project 中
        • 在另一个项目中
        • 手动输入

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

          • Project（项目）：输入或从下拉菜单中选择您的 Google Cloud 项目 ID。

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

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

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

  8. 点击连接。

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

    Cloud Build 会将创建的 GitHub 应用的身份验证数据作为 Secret Manager 中的密钥存储在项目中。这些数据包括您的私钥和 webhook 密钥。私钥用作访问企业服务器 API 的身份验证方法。网络钩子 Secret 用于验证从服务器发送到 Cloud Build 的事件。Cloud Build Service Agent 账号 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 用于访问您的 Secret。如需查看您的 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 应用名称：输入应用的名称。
    2. 首页网址：输入 GitHub Enterprise 服务器的网址。
    3. 取消选中过期用户授权令牌对应的复选框。
    4. 在 Webhook 部分中，完成以下步骤：
      • 有效：选中此复选框可激活您的网络图书。
      • Webhook 网址：输入您的 Webhook 网址。例如 https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook。Webhook 网址中的区域必须与您的连接区域一致。
      • Webhook 密文：输入一个随机生成的字符串，并记下该字符串。
    5. 在权限部分中，指定以下权限：
      • 代码库权限：
        • 检查：读取和写入
        • 内容：读取和写入
        • 问题：只读
        • 元数据 只读
        • 提交状态：只读
        • 拉取请求：只读
    6. 在订阅事件部分，勾选以下复选框：
      • 检查运行
      • 检查套件
      • 提交评论
      • 发出评论
      • 拉取请求
      • 拉取请求审核评论
      • 推送
      • 代码库
    7. 勾选任何账号对应的复选框，即可允许任何用户或组织安装您的 GitHub 应用。

  3. 点击 Create GitHub app 创建 GitHub 应用。

    点击 Create GitHub app 后，您会被重定向到应用页面。记下您的应用 ID 和应用 Slug。应用 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 应用的私钥和 Webhook Secret
  • 向 Cloud Build 服务代理授予访问 Secret 所需的权限

  • 创建 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 应用的网络钩子密钥的值。
  • 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 Manager 中存储 Secret：

    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 是您为网络钩子 Secret 创建的字符串。
    • PRIVATE_KEY_FILE 是您生成的私钥的文件路径。

  2. 向 Cloud Build 服务代理授予访问您的 Secret 的权限：

    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 关联。

后续步骤