此页面由 Cloud Translation API 翻译。

连接到 GitHub Enterprise 主机

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

准备工作

Enable the Cloud Build and Secret Manager APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

确保您拥有最新版本的 GitHub Enterprise。
确保将自定义网域映射到 GitHub Enterprise 主机，并且为您的主机具有有效的 SSL 证书。

注意：如果您的 GitHub Enterprise 主机在 Compute Engine 实例上运行，您可以创建外部 HTTP(s) 负载均衡器为实例使用 Google 管理的 SSL 证书。
如果您的 GitHub Enterprise 实例托管在专用网络中，请先参阅在专用网络中从 GitHub Enterprise 构建代码库，然后再完成本页上的说明。

必需的 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，请执行以下操作：

在 Google Cloud 控制台中打开代码库页面。

打开“代码库”页面

您将看到代码库页面。
在顶部栏的项目选择器中，选择您的 Google Cloud 项目。
在页面顶部，选择第 2 代标签页。
点击创建主机连接，将新主机连接到 Cloud Build。
在左侧面板中，选择 GitHub Enterprise 作为您的来源提供方。
在配置连接部分中，输入以下信息：
1. 区域：为连接选择一个区域。
  
  注意：您必须指定一个区域。您的连接无法全局存在。
2. 名称：输入连接的名称。
在主机详细信息部分中，输入以下信息：
1. 主机网址：输入连接的主机网址。例如 github.example.com
2. CA 证书：点击“浏览”以上传您的自签名证书。
  
  注意：您的证书大小不得超过 10 KB，并且应采用 PEM 格式（.pem、.cer 或 .crt）。如果此部分留空，则将使用一组默认证书。
3. 在连接类型下，选择以下选项之一：
  1. 公共互联网：如果您的实例可通过公共互联网访问，请选择此选项。
  2. 专用网络访问权限：如果您的实例托管在专用网络中，请选择此选项。
  3. 在 Service Directory 服务下，选择服务的位置：
    - 在项目 your-project 中
    - 在另一个项目中
    - 手动输入
    1. 如果您选择在其他项目中或手动输入，请输入以下信息：
      - 项目：输入您的 Google Cloud 项目 ID，或从下拉菜单中选择您的项目 ID。
      - 区域：此字段会预先选择连接所在的区域。为服务指定的区域必须与关联的连接所对应的区域一致。
    2. 命名空间：选择服务的命名空间。
    3. 服务：选择命名空间中的服务名称。
点击连接。

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

Cloud Build 会将创建的 GitHub 应用的身份验证数据作为密钥存储在您项目的 Secret Manager 中。此数据包括您的私钥和 Webhook 密钥。私钥用作一种身份验证方法，用于访问 Enterprise Server 的 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 的代码库页面。

gcloud

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

输入以下命令以创建 GitHub Enterprise 连接：
```
gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION
```
其中：
- CONNECTION_NAME 是 Cloud Build 中 GitHub Enterprise 主机连接的名称。
- 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 应用的链接。
按照上一步中返回的链接，在企业服务器上创建并安装 Cloud Build GitHub 应用。
输入以下命令以验证连接：
```
gcloud builds connections describe CONNECTION_NAME --region=REGION
```
其中：
- CONNECTION_NAME 是您的 GitHub Enterprise 主机连接在 Cloud Build 中的名称。
- REGION 是连接的区域。
如果 installationState 字段设置为 COMPLETE，则表示您已成功安装连接。否则，installationState 字段会提供一个链接，其中包含所需完成的其他步骤。

以程序化方式连接到 GitHub Enterprise 主机

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

注册新的 GitHub 应用。例如，您可以在 https://my-ghe-server.net/settings/apps/new 注册新的 GitHub 应用。
填写页面上的字段：
1. GitHub 应用名称：输入应用的名称。
2. 首页网址：输入 GitHub Enterprise Server 的网址。
3. 清除使用户授权令牌过期对应的复选框。
4. 在 Webhook 部分，完成以下步骤：
  - 有效：勾选此复选框可激活您的 webhook。
  - Webhook 网址：输入您的网络钩子网址。例如 https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook。网络钩子网址中的区域必须与连接的区域一致。
  - Webhook 密文：输入随机生成的字符串并记下该字符串。
5. 在权限部分中，指定以下权限：
  - 代码库权限：
    - 检查：读取和写入
    - 内容：读取和写入
    - 问题：只读
    - 元数据 只读
    - 提交状态：只读
    - 拉取请求：只读
6. 在订阅活动部分，勾选以下复选框：
  - 支票运行
  - 检查套件
  - 提交评论
  - 问题评论
  - 拉取请求
  - 拉取请求审核评论
  - 推送
  - 代码库
7. 勾选任何账号对应的复选框，以允许任何用户或组织安装您的 GitHub 应用。
点击 Create GitHub app 以创建 GitHub 应用。

点击 Create GitHub app 后，您将被重定向到应用页面。记下您的应用 ID 和应用 slug。应用别名可在相应网页网址的最后一段中找到。例如 https://my-ghe-server.net/settings/apps/{app-slug}
在私钥部分中，点击生成私钥。

将下载的文件存储在安全的位置。
在左侧窗格中，选择安装应用。

选择要安装应用的用户或组织。安装应用后，记下安装 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 应用私钥的密文。
WEBHOOK_SECRET 是包含 GitHub 应用的网络钩子密钥值的密钥名称。
WEBHOOK_SECRET_VALUE 是 GitHub 应用的网络钩子密钥的值。
REGION 是连接的区域。
CONNECTION_NAME 是 Cloud Build 中 GitHub Enterprise 主机连接的名称。
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。

gcloud

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

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

授予 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 是您的每个产品、每个项目的账号。

创建 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 是 Cloud Build 中 GitHub Enterprise 主机连接的名称。
- 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。
了解如何在 Compute Engine 上执行蓝绿部署。

连接到 GitHub Enterprise 主机 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

必需的 IAM 权限

连接到 GitHub Enterprise 主机

控制台

gcloud

以程序化方式连接到 GitHub Enterprise 主机

Terraform

gcloud

后续步骤

连接到 GitHub Enterprise 主机