本页面介绍了如何将 GitHub Enterprise 主机连接到 Cloud Build。
准备工作
-
启用 Cloud Build and Secret Manager API。
- 确保您拥有最新版本的 GitHub Enterprise。
确保将自定义网域映射到 GitHub Enterprise 主机,并且为您的主机具有有效的 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 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,请执行以下操作:
打开 Google Cloud 控制台中的制品库页面。
您将看到代码库页面。
在顶部栏的项目选择器中,选择您的 Google Cloud 项目。
在页面顶部,选择第 2 代标签页。
点击创建主机连接,将新主机连接到 Cloud Build。
在左侧面板中,选择 GitHub Enterprise 作为来源提供商。
在 Configure Connection 部分,输入以下信息:
区域:选择连接的区域。
名称:输入连接的名称。
在 Host details(主机详情)部分,输入以下信息:
Host 网址(主机网址):输入连接的主机网址。例如
github.example.com
CA 证书:点击“浏览”可上传您的自签名证书。
在连接类型下,选择以下选项之一:
公共互联网:如果您的实例可通过公共互联网访问,请选择此选项。
专用网络访问:如果您的实例托管在专用网络中,请选择此选项。
在 Service Directory 服务下,选择服务的位置:
- 在项目
your-project
中 - 在其他项目中
- 手动输入
如果您选择在其他项目中或手动输入,请输入以下信息:
项目:从下拉菜单中选择您的 Google Cloud 项目 ID。
区域:此字段会预先选择您的连接所在的区域。为您的服务指定的区域必须与您的连接关联的区域一致。
命名空间:选择服务的命名空间。
Service:选择命名空间中的服务名称。
- 在项目
点击连接。
点击连接按钮后,系统会要求您在 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,请完成以下步骤:
输入以下命令以创建 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 应用的链接。按照上一步中返回的链接,在您的企业服务器上创建并安装 Cloud Build GitHub 应用。
输入以下命令以验证连接:
gcloud builds connections describe CONNECTION_NAME --region=REGION
其中:
- CONNECTION_NAME 是您的连接的名称。
- REGION 是您的连接的区域。
如果
installationState
字段设置为COMPLETE
,则表示您已成功安装连接。否则,installationState
字段会提供相关额外步骤的链接。
现在,您已成功创建 GitHub Enterprise 连接。
以编程方式连接到 GitHub Enterprise 主机
如需以程序化方式将 GitHub Enterprise 主机连接到 Cloud Build,您必须完成以下步骤来安装 GitHub 应用:
注册一个新的 GitHub 应用。例如,您可以在
https://my-ghe-server.net/settings/apps/new
上注册一个新的 GitHub 应用。填写该页面上的字段:
- GitHub App Name:输入应用的名称。
- Homepage 网址(主页网址):输入您的 GitHub Enterprise 服务器的网址。
- 取消选中用户授权令牌过期对应的复选框。
- 在网络钩子部分,完成以下步骤:
- 有效:选中该复选框即可激活您的 Webook。
- 网络钩子网址:输入您的网络钩子网址。例如
https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook
。网络钩子网址中的区域必须与连接的区域一致。 - 网络钩子密钥:输入随机生成的字符串并记下该字符串。
- 在权限部分,指定以下权限:
- 代码库权限:
- 检查:读取和写入
- 内容:读取和写入
- 问题:只读
- 元数据(只读)
- 提交状态:只读
- 拉取请求:只读
- 代码库权限:
- 在订阅活动部分,勾选以下复选框:
- 检查运行
- 检查套件
- 提交评论
- 问题备注
- 拉取请求
- 拉取请求审核备注
- 推送
- 代码库
- 勾选任何帐号对应的复选框,以允许任何用户或组织安装您的 GitHub 应用。
点击创建 GitHub 应用以创建 GitHub 应用。
点击创建 GitHub 应用后,您将被重定向到您的应用页面。记下您的应用 ID 和应用标识符。您可在页面网址的最后一部分找到 App 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 应用的私钥和网络钩子密钥
- 向 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 主机:
将您的 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 是您生成的私钥的文件路径。
向 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 是您按产品划分的帐号。
创建 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 连接。