連結至 GitLab Enterprise Edition 主機

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

事前準備

  • 如果尚未啟用 Cloud Build 和 Secret Manager API，請啟用這些 API。

    啟用 API 時所需的角色

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

    啟用 API

主機需求

  • 如果尚未安裝 GitLab Enterprise Edition Server 執行個體，請參閱 GitLab Enterprise Edition 的安裝指南，瞭解相關操作說明。

    按照操作說明安裝 GitLab Enterprise Edition 伺服器執行個體時，請注意下列事項：

    • 你必須設定主機來處理 HTTPS 通訊協定。不支援使用 HTTP 通訊協定設定的主機。

    • 您必須使用與從 Google Cloud連線至主機時相同的網址，設定主機。詳情請參閱 GitLab 說明文件，瞭解如何設定外部網址。

必要 IAM 權限

如要連結 GitLab Enterprise Edition 主機，請將 Cloud Build 連線管理員 (roles/cloudbuild.connectionAdmin) 角色授予使用者帳戶。

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

如果 GitLab Enterprise Edition 執行個體託管於私人網路，請參閱「在私人網路中從 GitLab Enterprise Edition 建構存放區」，瞭解主機連線前所需的其他 IAM 角色。

連線至 GitLab Enterprise Edition 主機

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

  1. 登入 GitLab Enterprise Edition 執行個體。

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

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

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

    系統會顯示「Personal Access Tokens」頁面。

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

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

控制台

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

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

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

    畫面會顯示「Repositories」(存放區) 頁面。

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

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

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

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

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

    • 區域：選取連線的區域。

    • 名稱：輸入連線名稱。

  7. 在「主機詳細資料」部分，選取或輸入下列資訊：

    • GitLab 主機：選取「自行管理的 GitLab Enterprise Edition」。

    • 主機網址：輸入連線的主機網址。例如：https://my-gle-server.net。

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

  9. 在「Networking」(網路) 專區的「Connection type」(連線類型) 下方，選取下列其中一個選項：

    • 公開網際網路：如果執行個體可透過公開網際網路存取，請選取這個選項。

    • 私人網路：如果執行個體託管於私人網路，請選取這個選項。然後設定下列項目：

      1. CA 憑證：按一下「瀏覽」上傳自行簽署的憑證。

      2. 在「服務目錄服務」下方，選取服務地點：

        • 在「CURRENT_PROJECT」專案中
        • 在其他專案中
        • 手動輸入

      3. 輸入下列資訊：

        • 專案：如果您選取「在其他專案中」或「手動輸入」，請輸入或從下拉式選單中選取 Google Cloud 專案 ID。

        • 區域：這個欄位會預先選取連線區域。為服務指定的區域必須與連線相關聯的區域相符。

        • 命名空間：選取服務的命名空間。

        • 服務：選取命名空間中的服務名稱。

  10. 在「Personal access tokens」(個人存取權杖) 部分，輸入下列資訊：

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

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

  11. 按一下「連線」。

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

gcloud

將 GitLab Enterprise Edition 主機連線至 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 Enterprise Edition 主機連結至 Cloud Build。

操作步驟如下：

  1. 輸入下列指令，建立 GitLab Enterprise Edition 連線：

    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 中的連線名稱。
    • HOST_URI 是 GitLab Enterprise Edition 執行個體的 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 Enterprise Edition 連線。

Terraform

您可以使用 Terraform，將 GitLab Enterprise Edition 主機連結至 Cloud Build。進一步瞭解 Google Cloud上的 Terraform。

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

  • 設定 Terraform 資源供應商 Google Cloud
  • 建立密鑰，用於儲存 GitLab Enterprise Edition 個人存取權杖
  • 授予 Cloud Build 服務代理存取密鑰的必要權限

  • 建立 GitLab Enterprise Edition 連線

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

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "api-pat-secret" {
    project = "PROJECT_ID"
    secret_id = "GITLAB_PAT_API"

    replication {
        auto {}
     }
 }

 resource "google_secret_manager_secret_version" "api-pat-secret-version" {
     secret = google_secret_manager_secret.api-pat-secret.id
     secret_data = "GITLAB_API_TOKEN"
 }

 resource "google_secret_manager_secret" "read-pat-secret" {
     project = "PROJECT_ID"
     secret_id = "GITLAB_PAT_READ"

     replication {
         auto {}
     }
}

resource "google_secret_manager_secret_version" "read-pat-secret-version" {
    secret = google_secret_manager_secret.read-pat-secret.id
    secret_data = "GITLAB_API_TOKEN"
}

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-pak" {
  project = google_secret_manager_secret.api-pat-secret.project
  secret_id = google_secret_manager_secret.api-pat-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-pat-secret.project
  secret_id = google_secret_manager_secret.read-pat-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"

    gitlab_config {
        host_uri = "URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.api-pat-secret-version.id
        }
        read_authorizer_credential {
             user_token_secret_version = google_secret_manager_secret_version.read-pat-secret-version.id
        }
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pak,
        google_secret_manager_secret_iam_policy.policy-rpak,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

更改下列內容：

  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • GITLAB_PAT_API：具有 api存取權的個人存取權杖。
  • GITLAB_API_TOKEN：您的個人存取權杖。
  • GITLAB_PAT_READ：具有 read_api 存取權的個人存取權杖。
  • WEBHOOK_SECRET：包含 Webhook Secret 值的 Secret 名稱。
  • WEBHOOK_SECRET_VALUE：網路鉤子密鑰的值。

  • PROJECT_NUMBER：您的 Google Cloud 專案號碼。您可以在 Google Cloud 控制台的「歡迎」頁面找到專案編號，也可以執行下列指令：

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  • REGION：連線的區域。

  • CONNECTION_NAME：Cloud Build 中 GitLab Enterprise 版本的主機連線名稱。

  • URI：連線的 URI，例如 https://my-gitlab-enterprise-server.net。

您已成功建立 GitLab Enterprise Edition 連線。

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

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

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

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

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

  1. 在 GitLab Enterprise Edition 中輪替每個存取權杖：

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

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

    3. 複製輪替權杖的 ID。

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

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

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

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

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

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

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

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

後續步驟