連結至 GitLab 主機

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

事前準備

  • 啟用 Cloud Build 和 Secret Manager API。

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

連結至 GitLab 主機

為 GitLab 執行個體建立主機連線前，請先在 GitLab 中建立個人存取權杖，方法如下：

  1. 登入 GitLab 執行個體。

  2. 在執行個體的 GitLab 頁面中，按一下右上角的顯示圖片。

  3. 按一下 [編輯個人資料]。

  4. 在左側邊欄中，選取「存取權杖」。

    畫面會顯示「Personal Access Tokens」(個人存取權杖) 頁面。

  5. 建立具備 api 範圍的存取權杖，用於連結及取消連結存放區。

  6. 建立具備 read_api 範圍的存取權杖，確保 Cloud Build 存放區可以存取存放區中的原始碼。

控制台

如要將 GitLab 主機連結至 Cloud Build，請按照下列步驟操作：

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

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

    畫面會顯示「Repositories」頁面。

  2. 選取頁面頂端的「第 2 代」分頁標籤。

  3. 在頂端列的專案選取器中，選取您的 Google Cloud 專案。

  4. 按一下「建立主機連線」，將新主機連結至 Cloud Build。

  5. 在左側面板中，選取「GitLab」GitLab做為來源供應商。

  6. 在「設定連線」部分，輸入下列資訊：

    • 「Region」(區域)：選取連線的區域。

    • 名稱：輸入連線名稱。

  7. 在「主機詳細資料」部分，前往「GitLab 主機」，然後選取「GitLab.com」。

  8. 選用：如要管理用於加密 GitLab 存放區存取權杖的加密金鑰，請前往「Encryption」(加密) 部分，然後選擇 Cloud Key Management Service 金鑰。詳情請參閱「為 Secret Manager 啟用客戶管理的加密金鑰」。

  9. 在「Personal access tokens」部分，輸入下列資訊：

    • API 存取權杖：輸入具有 api 範圍存取權的權杖。這個權杖用於連結及取消連結存放區。

    • 讀取 API 存取權杖：輸入具有 read_api 範圍存取權的權杖。Cloud Build 觸發條件會使用這個權杖存取存放區中的原始碼。

  10. 按一下「連線」。

    按一下「連線」按鈕後，系統會將個人存取權杖安全地儲存在 Secret Manager 中。建立主機連線後，Cloud Build 也會代您建立 Webhook 密鑰。您可以在「Secret Manager」頁面查看及管理密鑰。

您已成功建立 GitLab 連線。

gcloud

將 GitLab 主機連結至 Cloud Build 之前，請先完成下列步驟來儲存憑證：

  1. 將權杖儲存在 Secret Manager。

  2. 執行下列指令，在 Secret Manager 中建立 Webhook 密鑰：

     cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-

  3. 如果將密鑰儲存在與建立主機連線的專案不同的 Google Cloud 專案中，請輸入下列指令，授予專案 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"

    其中：

    • PROJECT_ID 是您的 Google Cloud 專案 ID。

現在可以繼續將 GitLab 主機連結至 Cloud Build。

操作步驟如下：

如要將 GitLab 主機連結至 Cloud Build，請按照下列步驟操作：

  1. 輸入下列指令來建立 GitLab 連線：

    gcloud builds connections create gitlab CONNECTION_NAME \
  --host-uri=HOST_URI \
  --project=PROJECT_ID \
  --region=REGION \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/API_TOKEN/versions/SECRET_VERSION \
  --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION

    其中：

    • CONNECTION_NAME 是 Cloud Build 中的 GitLab 主機連線名稱。
    • HOST_URI 是 GitLab 執行個體的 URI。例如：https://my-gle-server.net。
    • PROJECT_ID 是您的 Google Cloud 專案 ID。
    • REGION 是連線的區域。
    • API_TOKEN 是具有 apiscope 的權杖名稱。
    • READ_TOKEN 是具有 read_apiscope 的權杖名稱。
    • SECRET_VERSION 是密鑰的版本。
    • WEBHOOK_SECRET 是您的 Webhook 密鑰。

您已成功建立 GitLab 連線。

輪替舊的或過期的 GitLab 存取權杖

輪替存取權杖，讓 Cloud Build 主機連線維持與 GitLab 存放區的連線。如果 GitLab 存取權杖過期，Cloud Build 主機連線就會與 GitLab 存放區中斷連線。發生這種情況時，您必須輪替過期的權杖，才能停用連線或連結存放區。此外，在下列情況下，您也會看到錯誤訊息：

  • 連線的「連線詳細資料」頁面會顯示錯誤訊息 Connection is disconnected due to an invalid or expired access token。

  • 如果嘗試將存放區連結至權杖過期的連線，系統會顯示「Invalid access token」(無效的存取權杖) 訊息。按一下「查看連結」會前往「連結詳細資料」頁面，查看權杖過期的連結。

Cloud Build 可讓您輸入新的權杖值，並將這些權杖儲存在 Secret Manager 的最新密鑰版本中，藉此輪替存取權杖。如要輪替存取權杖，請按照下列步驟操作：

  1. 在 GitLab 中輪換每個存取權杖：

    1. 前往連結至 Cloud Build 主機連線的 GitLab 存放區。

    2. 請按照 GitLab 說明文件中的操作說明輪替存取權杖。 當您輪替權杖時，GitLab 會建立具有新憑證的新權杖，並使該權杖的舊版失效。輪替後的權杖與原始權杖的權限和範圍相同。

    3. 複製輪替權杖的 ID。

  2. 在 Cloud Build 中更新存取權杖：

    1. 前往連線的「連線詳細資料」頁面。

    2. 選取「更新存取權杖」。

    3. 在「權杖輪替」選單中，於「API 存取權杖」和「讀取存取權杖」欄位輸入新權杖。

    4. (選用)：如要讓連線一律使用最新版權杖密鑰，請選取「將連線更新為一律使用最新版本」。如果連線使用特定密鑰版本號碼，取消選取這個選項可能會有幫助。

    5. 選取「更新」即可儲存變更。

      Cloud Build 會將新存取權杖儲存至 Secret Manager，做為最新版本的密鑰。

詳情請參閱 GitLab 說明文件中的「存取權杖到期」。

後續步驟