Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

连接到 GitHub 代码库

本页介绍了如何将 GitHub 代码库连接到 Cloud Build。如需详细了解 Cloud Build 代码库，请参阅 Cloud Build 代码库。

准备工作

启用 Cloud Build API 和 Secret Manager API。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API

在 GitHub 代码库中准备好源代码。
GitHub 源代码库中包含 Dockerfile 或 Cloud Build 配置文件。
如果您最初将代码库连接到 Cloud Build，请确保对代码库具有管理员级别权限。如需详细了解 GitHub 代码库权限，请参阅组织的代码库权限级别。
如需使用此页面上的 gcloud 命令，请安装 Google Cloud CLI。

注意：如果您之前已经安装了 gcloud CLI，请运行 gcloud components update 以确保您拥有最新版本。

连接到 GitHub 托管服务

控制台

如需将 GitHub 代码库连接到 Cloud Build，请执行以下操作：

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

打开“代码库”页面

您会看到代码库页面。
在顶部栏的项目选择器中，选择您的 Google Cloud 项目。
选择页面顶部的第 2 代标签页。
点击创建主机连接，将新主机连接到 Cloud Build。
在左侧面板中，选择 GitHub 作为您的来源提供方。
在配置连接部分中，输入以下信息：
- 区域：为连接选择一个区域。
  
  注意：您必须指定一个区域。您的连接无法全局存在。
- 名称：输入连接的名称。
可选：如果您想管理用于加密 GitHub 代码库的访问令牌的加密密钥，请前往加密部分，然后选择 Cloud Key Management Service 密钥。如需了解详情，请参阅为 Secret Manager 启用客户管理的加密密钥。
点击连接。

点击关联按钮后，系统会要求您授权 Cloud Build GitHub 应用访问您的 GitHub 账号。您可以随时从主机上卸载或删除该应用来撤消对该应用的访问权限。

Cloud Build 会请求对您的 GitHub 用户账号进行授权，并将生成的授权令牌作为密钥存储在您项目的 Secret Manager 中。授权令牌用于验证您的用户账号是否具有安装 Cloud Build GitHub 应用以及访问关联代码库的权限。Cloud Build Service Agent 账号 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 用于访问您的 Secret。如需查看您的 Secret，请参阅列出 Secret 并查看 Secret 详情。

注意：此身份验证可用于在同一项目中创建其他连接。我们建议您使用机器人账号或团队共享的账号，而不是个人 GitHub 账号，以确保连接安全。

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

gcloud

如需使用 gcloud 连接 GitHub 主机，请完成以下步骤：

输入以下命令以发起与 GitHub 代码库的连接：
```
 gcloud builds connections create github CONNECTION_NAME --region=REGION
```
其中：
- CONNECTION_NAME 是连接的名称，它将显示在 Cloud Build 中。
- REGION 是触发器的区域。
  
  注意：您必须指定一个区域。您的连接无法全局存在。
运行 gcloud builds connections 命令后，您会看到一个用于授权 Cloud Build GitHub 应用的链接。
登录您的 github.com 账号。

注意：此身份验证可用于在同一项目中创建其他连接。我们建议您使用机器人账号或团队共享的账号，而不是个人 GitHub 账号，以确保连接安全无虞。
点击相应链接，授权 Cloud Build GitHub 应用。

授权应用后，Cloud Build 会将身份验证令牌作为密钥存储在您 Google Cloud项目中的 Secret Manager 中。您可以在 Secret Manager 页面上查看 Secret。
请登录您的账号或您拥有的组织账号来安装 Cloud Build GitHub 应用。

您需要使用自己的 GitHub 账号来授权安装操作，并在出现提示时选择代码库权限。
运行以下命令，验证 GitHub 连接是否已安装：
```
 gcloud builds connections describe CONNECTION_NAME --region=REGION
```
其中：
- CONNECTION_NAME 是您的 GitHub 主机连接在 Cloud Build 中的名称。
- REGION 是触发器的区域。
如果 installationState 字段设置为 COMPLETE，则表示您已成功安装连接。否则，installationState 字段会提供一个链接，其中包含所需完成的其他步骤。

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

如需以编程方式连接到 GitHub 主机，您必须先为连接配置身份验证令牌，然后在 Cloud Build 中创建 GitHub 连接。

配置身份验证令牌

如需以程序化方式连接到 GitHub 主机，您必须创建 Cloud Build GitHub 连接，包括身份验证令牌的 Secret。您可以通过两种方式获取身份验证令牌：

在 GitHub 中创建个人访问令牌。

注意： Cloud Build 不支持使用 GitHub 精细访问令牌。
使用现有 Cloud Build GitHub 连接中的令牌。如果您的 GitHub 账号受到限制，无法创建个人访问令牌，此方法会很有用。此外，如果您在通过脚本创建连接时引用此令牌，则无需使用网络浏览器手动对连接进行身份验证。

个人访问令牌

按照 GitHub 文档中的步骤创建个人访问令牌。
在 GitHub 中收到提示时，请选择以下 OAuth 范围：
- repo 以授予对公共代码库和私有代码库的完全访问权限。
- read:user 以授予读取用户个人资料数据的权限。
- read:org 用于对组织成员资格和项目（如果您的应用安装在组织中）进行只读访问。
注意：当令牌过期时，您需要删除过期的令牌并创建一个新令牌。
保存个人访问令牌的值。您将在后面的步骤中用到它。

现有连接

在 gcloud CLI 中运行以下命令：
```
gcloud builds connections describe CONNECTION_NAME --region=REGION
```
其中：
- CONNECTION_NAME 是您的 GitHub 主机连接的名称。
- REGION 是触发器的区域。
在命令输出中，authorizerTokenSecretVersion 的值是包含连接的身份验证令牌的 Secret 的 ID。复制此值并将其保存在安全的位置。您将在后续步骤中使用生成的令牌。

注意：如果您尚未在 Cloud Build 中建立 GitHub 连接，但想使用 Cloud Build 连接的身份验证令牌，请运行 gcloud builds connections create github CONNECTION_NAME --region=REGION 以创建一个连接。然后，您可以运行 gcloud build connections describe 来检索相应连接的 Secret，并在后续步骤中创建与 GitHub 的连接时使用该 Secret。

创建 GitHub 连接

使用 Terraform 或 gcloud CLI 创建 GitHub 连接。

Terraform

您可以使用 Google Terraform 提供程序将 GitHub 主机连接到 Cloud Build，只需完成以下步骤：

在您的 GitHub 账号或您拥有的组织账号中安装 Cloud Build GitHub 应用。

在 Terraform 中配置 GitHub 连接。以下 Terraform 代码示例展示了一个执行以下操作的配置：

配置 Terraform Google 提供程序
创建用于存储 GitHub 个人访问令牌的 Secret
向 Cloud Build 服务代理授予访问相应 Secret 的权限
创建 GitHub 连接

// Configure the terraform google provider
terraform {
  required_providers {
    google = {}
    }
}

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

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" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

其中：

PROJECT_NUMBER 是您的 Google Cloud 项目编号。
SECRET_ID 是 Secret Manager 中 GitHub 个人访问令牌或密钥的 ID。
GITHUB_PAT 是 GitHub 中个人访问令牌的访问令牌。
PROJECT_ID 是 Google Cloud 项目 ID。
REGION 是连接的区域。
CONNECTION_NAME 是连接的名称，它将显示在 Cloud Build 中。
INSTALLATION_ID 是 Cloud Build GitHub 应用的安装 ID。您可以在 Cloud Build GitHub 应用的网址中找到安装 ID。在以下网址 https://github.com/settings/installations/1234567 中，安装 ID 是数值 1234567。

gcloud

如需将 GitHub 主机连接到 Cloud Build，请执行以下操作：

在您的 GitHub 账号或您拥有的组织账号中安装 Cloud Build GitHub 应用。
可选。如果您使用 GitHub 个人访问令牌进行身份验证，请运行以下命令，将令牌存储在 Google Cloud 项目的 Secret Manager 中：
```
echo -n 'TOKEN' | gcloud secrets create SECRET_NAME --data-file=-
```

向 Cloud Build 服务代理授予对 Secret 的访问权限，其中 SECRET_NAME 是存储在 Secret Manager 中的 Secret 的名称：

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

创建 GitHub 连接：
```
gcloud builds connections create github CONNECTION_NAME \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION  \
  --app-installation-id=INSTALLATION_ID --region=REGION
```
其中：
- CONNECTION_NAME 是您的 GitHub 主机连接在 Cloud Build 中的名称。
- PROJECT_ID 是 Google Cloud 项目 ID。
- SECRET_NAME 是存储在 Secret Manager 中的 Secret 的名称。
- VERSION 是 Secret 的版本。
- INSTALLATION_ID 是 GitHub 应用的安装 ID。您可以在 Cloud Build GitHub 应用的网址中找到安装 ID。在以下网址中，https://github.com/settings/installations/1234567 是安装 ID，即数值 1234567。
- REGION 是连接的区域。

关联 GitHub 代码库

控制台

如需将 GitHub 代码库连接到主机连接，请完成以下步骤：

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

打开“代码库”页面

您会看到代码库页面。
选择页面顶部的第 2 代标签页。
点击关联代码库以关联连接中的代码库。

您会看到关联代码库面板。
在关联代码库面板中，输入以下信息：
1. 连接：从下拉菜单中选择连接。
2. 代码库：选择要与连接相关联的代码库。
3. 代码库名称：输入代码库的名称。
  1. 生成：选择此选项可让 Cloud Build 自动为所选代码库生成代码库名称。
  2. 手动：选择此选项可手动为所选代码库指定名称。
    
    如果您选择手动，则可以在代码库名称部分修改所选代码库的名称。
点击关联，将代码库与连接相关联。

gcloud

如需向连接中添加 GitHub 代码库，请输入以下命令：

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

其中：

REPO_NAME 是代码库的名称。
REPO_URI 是指向 GitHub 代码库的链接。例如 https://github.com/cloud-build/test-repo.git。
CONNECTION_NAME 是在 Cloud Build 中通过连接到 GitHub 主机创建的 GitHub Enterprise 主机连接的名称。
REGION 是连接的区域。

Terraform

如需向连接添加 GitHub 代码库，请将以下代码段添加到您的 Terraform 配置中：

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

其中：

PROJECT_ID 是 Google Cloud 项目 ID。
REPO_NAME 是您的 GitHub 代码库的名称。
REGION 是连接的区域。
URI 是代码库的主机 URI。例如 https://github.com/myuser/myrepo.git。

后续步骤

了解如何从 GitHub 构建代码库。
了解如何在 Compute Engine 上执行蓝绿部署。
了解如何指定其他代码库作为 build 的依赖项。

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

准备工作

连接到 GitHub 托管服务

控制台

gcloud

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

配置身份验证令牌

个人访问令牌

现有连接

创建 GitHub 连接

Terraform

gcloud

关联 GitHub 代码库

控制台

gcloud

Terraform

后续步骤

连接到 GitHub 代码库