本頁面由 Cloud Translation API 翻譯而成。

連結至 GitHub 存放區

本頁說明如何將 GitHub 存放區連結至 Cloud Build。如要進一步瞭解 Cloud Build 存放區，請參閱「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 存放區中準備好原始碼。
在 GitHub 來源存放區中，擁有 Dockerfile 或 Cloud Build 設定檔。
如果一開始是將存放區連結至 Cloud Build，請確認您對存放區擁有管理員層級的權限。如要進一步瞭解 GitHub 存放區權限，請參閱「機構的存放區權限等級」。
如要在本頁面使用 gcloud 指令，請安裝 Google Cloud CLI。

注意： 如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

必要 IAM 權限

如要連結 GitHub 主機，請將 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 主機

主控台

如要將 GitHub 存放區連結至 Cloud Build，請按照下列步驟操作：

在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

開啟「Repositories」(存放區) 頁面

畫面會顯示「Repositories」(存放區) 頁面。
在頂端列的專案選取器中，選取 Google Cloud 專案。
選取頁面頂端的「第 2 代」分頁標籤。
按一下「建立主機連線」，將新主機連結至 Cloud Build。
在左側面板中，選取「GitHub」GitHub做為來源供應商。
在「設定連線」部分，輸入下列資訊：
1. 「Region」(區域)：選取連線的區域。
  
  注意： 您必須指定區域。你的連線無法在全球範圍內存在。
2. 名稱：輸入連線名稱。
按一下「連線」。

點選「連線」按鈕後，系統會要求您授權 Cloud Build GitHub 應用程式存取 GitHub 帳戶。您隨時可以從主機解除安裝或刪除應用程式，藉此撤銷應用程式的存取權。

Cloud Build 會要求授權存取您的 GitHub 使用者帳戶，並將產生的授權權杖以密鑰形式儲存在專案的 Secret Manager 中。授權權杖用於驗證使用者帳戶的存取權，以便安裝 Cloud Build GitHub 應用程式，以及連結至相關存放區。Cloud Build 服務代理人帳戶 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 用於存取密鑰。如要查看密鑰，請參閱「列出密鑰並查看密鑰詳細資料」。

注意： 您可以使用這項驗證，在同一個專案中建立其他連線。建議使用機器人帳戶或團隊共用的帳戶，而非個人 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 會將驗證權杖以密鑰的形式儲存在專案的 Secret Manager 中。 Google Cloud您可以在「Secret Manager」頁面查看密鑰。
在您的帳戶或組織中安裝 Cloud Build GitHub 應用程式。

使用 GitHub 帳戶允許安裝，並在系統提示時選取存放區權限。
執行下列指令，確認 GitHub 連線安裝作業：
```
 gcloud builds connections describe CONNECTION_NAME --region=REGION
```
其中：
- CONNECTION_NAME 是 Cloud Build 中 GitHub 主機連線的名稱。
- REGION 是觸發條件的區域。
如果 installationState 欄位設為 COMPLETE，表示您已成功安裝連線。否則，installationState 欄位會提供連結，引導您完成其他必要步驟。

透過程式輔助方式連線至 GitHub 主機

Terraform

如要使用 Google Terraform 供應商將 GitHub 主機連至 Cloud Build，請完成下列步驟：

在您的 GitHub 帳戶或所屬機構中安裝 Cloud Build GitHub 應用程式。
建立個人存取權杖。

請務必將權杖設為永不過期，並在 GitHub 提示時選取下列權限：repo 和 read:user。如果應用程式安裝在機構中，請務必選取 read:org 權限。

產生個人存取權杖後，請將權杖儲存於安全的位置。您會在後續步驟中使用產生的權杖。

注意： 如果您先前建立的連線已將驗證權杖儲存在祕密中，則可將該祕密用於新連線。

在以下範例中，程式碼片段會執行下列操作：

設定 Terraform Google 提供者
建立密鑰來儲存 GitHub 個人存取權杖，並授予 Cloud Build 服務代理程式存取密鑰的權限

建立 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 中的權杖或密鑰 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

如要使用先前連線取得的現有權杖和安裝 ID 連線至 GitHub 主機，請完成下列步驟：

在您的 GitHub 帳戶或所屬機構中安裝 Cloud Build GitHub 應用程式。
建立個人存取權杖。

請務必將權杖設為永不過期，並在 GitHub 提示時選取下列權限：repo 和 read:user。如果應用程式安裝在機構中，請務必選取 read:org 權限。

產生個人存取權杖後，請將權杖儲存於安全的位置。您會在後續步驟中使用產生的權杖。

注意： 如果您先前建立的連線已將驗證權杖儲存在祕密中，則可將該祕密用於新連線。
執行下列指令，將權杖儲存在 Google Cloud 專案的 Secret Manager 中：
```
    echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-
```
其中：
- TOKEN 是您的個人存取權杖。
- SECRET_NAME 是您要在 Secret Manager 中為密鑰命名的名稱。

授予 Cloud Build 服務代理密鑰的存取權，其中 SECRET_NAME 是儲存在 Secret Manager 中的密鑰名稱：

  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/1  \
    --app-installation-id=INSTALLATION_ID --region=REGION
```
其中：
- CONNECTION_NAME 是 Cloud Build 中 GitHub 主機連線的名稱。
- PROJECT_ID 是您的 Google Cloud 專案 ID。
- SECRET_NAME 是儲存在 Secret Manager 中的密鑰名稱。
- INSTALLATION_ID 是 GitHub 應用程式的安裝 ID。您可以在 Cloud Build GitHub 應用程式的網址中找到安裝 ID。在下列網址中，https://github.com/settings/installations/1234567，安裝 ID 是數值 1234567。
- REGION 是連線的區域。

連結 GitHub 存放區

主控台

如要將 GitHub 存放區連結至主機連線，請完成下列步驟：

在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

開啟「Repositories」(存放區) 頁面

畫面會顯示「Repositories」(存放區) 頁面。
選取頁面頂端的「第 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 是在「連結至 GitHub 主機」中，於 Cloud Build 建立的 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 上執行藍綠部署。
瞭解如何指定其他存放區做為建構作業的依附元件。