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

連結至 GitHub Enterprise 主機

本頁說明如何將 GitHub Enterprise 主機連結至 Cloud Build。

事前準備

Enable the Cloud Build and Secret Manager APIs.
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 連線管理員 (roles/cloudbuild.connectionAdmin) 角色授予使用者帳戶。

如要為使用者帳戶新增必要角色，請參閱「設定 Cloud Build 資源的存取權」。如要進一步瞭解與 Cloud Build 相關的 IAM 角色，請參閱「IAM 角色和權限」一文。

如要使用 gcloud 安裝步驟建立連線，請在 Google Cloud 專案中執行下列指令，將 Secret Manager 管理員角色 (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 控制台中開啟「Repositories」頁面。

開啟「存放區」頁面

畫面會顯示「Repositories」頁面。
在頂端列的專案選取器中，選取 Google Cloud 專案。
選取頁面頂端的「第 2 代」分頁標籤。
按一下「建立主機連線」，將新的主機連結至 Cloud Build。
在左側面板中，選取「GitHub Enterprise」做為來源供應工具。
在「Configure Connection」(設定連線) 部分，輸入下列資訊：
1. 區域：選取連線的區域。
  
  注意： 您必須指定區域。您的連線無法在全球範圍內運作。
2. 名稱：輸入連線名稱。
在「Host details」(主機詳細資料) 部分輸入以下資訊：
1. 主機網址：輸入連線的主機網址。例如：github.example.com
2. CA 憑證：按一下「瀏覽」上傳自行簽署的憑證。
  
  注意： 您的憑證大小不得超過 10 KB，且應採用 PEM 格式 (.pem、.cer 或 .crt)。如果這個部分留空，系統會使用預設的憑證組合。
3. 在「連線類型」下方，選取下列任一選項：
  1. 公開網際網路：如果您可以透過公開網際網路存取執行個體，請選取這個選項。
  2. 私人網路存取權：如果執行個體是託管在私人網路中，請選取這個選項。
  3. 在「服務目錄服務」下方，選取服務的位置：
    - 在「your-project」專案中
    - 在其他專案中
    - 手動輸入
    1. 如果您選取「位於其他專案」或「手動輸入」，請輸入下列資訊：
      - 專案：輸入或從下拉式選單中選取 Google Cloud 專案 ID。
      - 區域：這個欄位會預先選取連線的區域。您為服務指定的地區必須與連線關聯的地區相符。
    2. 命名空間：選取服務的命名空間。
    3. 服務：選取命名空間中的服務名稱。
按一下「連線」。

點選「連線」按鈕後，系統會要求您在 GitHub Enterprise 主機建立 GitHub 應用程式，並在使用者帳戶或機構中安裝應用程式。系統會建立 GitHub Enterprise 主機的驗證權杖，並將驗證權杖以 Secret Manager 密鑰的形式儲存在這項專案中。您隨時可以從主機解除安裝或刪除 GitHub 應用程式，藉此撤銷存取權。

Cloud Build 會將建立的 GitHub 應用程式驗證資料儲存在專案中 Secret Manager 的密鑰中。這類資料包括私密金鑰和 webhook 密鑰。私密金鑰可做為驗證方法，用於存取 Enterprise Server 的 API。Webhook 密鑰可用於驗證從伺服器傳送至 Cloud Build 的事件。Cloud Build 服務代理人帳戶 (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) 會用來存取您的機密資料。如要查看密鑰，請參閱「列出密鑰並查看密鑰詳細資料」一文。

授權 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 是 Cloud Build 中 GitHub Enterprise 主機連線的名稱。
- 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. 取消勾選「Expire user authorization tokens」方塊。
4. 在「Webhook」部分中，完成下列步驟：
  - 啟用：勾選這個方塊即可啟用網上書籍。
  - Webhook 網址：輸入 Webhook 網址。例如，https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook。webhook 網址中的區域必須與連線的區域相符。
  - Webhook 密鑰：輸入隨機產生的字串，並記下這組字串。
5. 在「Permissions」部分中，指定下列權限：
  - 存放區權限：
    - 檢查：讀取和寫入
    - 內容：讀取和寫入
    - Issues：唯讀
    - 中繼資料 唯讀
    - 提交狀態：唯讀
    - 提取要求：唯讀
6. 在「訂閱事件」部分，勾選下列方塊：
  - 檢查執行狀況
  - 檢查套件
  - 修訂版本註解
  - 問題註解
  - 提取要求
  - 提取要求審查留言
  - 推送
  - 存放區
7. 勾選「任何帳戶」方塊，允許任何使用者或機構安裝 GitHub 應用程式。
按一下「建立 GitHub 應用程式」，即可建立 GitHub 應用程式。

點選「Create GitHub app」後，系統會將您重新導向至應用程式頁面。請記下應用程式 ID 和應用程式縮寫。應用程式短代碼位於網頁網址的最後一個部分。例如：https://my-ghe-server.net/settings/apps/{app-slug}
在「Private keys」部分，按一下「Generate a private key」。

將下載的檔案儲存在安全的位置。
在左側窗格中，選取「安裝應用程式」。

選取要安裝應用程式的使用者或機構。安裝應用程式後，請記下安裝 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 密鑰
將必要權限授予 Cloud Build 服務代理，以便存取密鑰

建立 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 密鑰值的密鑰名稱。
WEBHOOK_SECRET_VALUE 是 GitHub 應用程式的 Webhook 密鑰值。
REGION 是連線的地區。
CONNECTION_NAME 是 Cloud Build 中 GitHub Enterprise 主機連線的名稱。
URI 是連線的 URI。例如：https://my-github-enterprise-server.net。
APP_ID 是 GitHub 應用程式的 ID。
APP_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 應用程式後，請完成下列步驟，透過程式設計連結 GitHub Enterprise 主機：gcloud：

將密鑰儲存於 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 是您為 Webhook 密鑰建立的字串。
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 是 Per-Product Per-Project 帳戶。

建立 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 是應用程式路徑代碼。例如：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 主機