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

連結至 GitLab Enterprise Edition 主機

本頁說明如何將 GitLab Enterprise Edition 主機連線至 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

主機需求

如果尚未安裝 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 中建立個人存取權杖：

登入 GitLab Enterprise Edition 執行個體。
在您執行個體的 GitLab Enterprise Edition 頁面中，按一下右上角的顯示圖片。
按一下 [編輯個人資料]。
在左側邊欄中，選取「存取權杖」。

系統會顯示「個人存取權杖」頁面。
建立具備 api 範圍的存取權杖，用於連結及取消連結存放區。
建立具備 read_api 範圍的存取權杖，確保 Cloud Build 存放區可以存取存放區中的原始碼。

注意： 除了個人存取權杖，您也可以使用專案存取權杖。如果您的 GitLab 版本為 14.2 以上，也可以使用群組存取權杖。如果您使用專案或群組存取權權杖，請選取 Maintainer 角色，確保連線成功。

控制台

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

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

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

畫面會顯示「Repositories」頁面。
選取頁面頂端的「第 2 代」分頁標籤。
在頂端列的專案選取器中，選取 Google Cloud 專案。
按一下「建立主機連線」，將新主機連結至 Cloud Build。
在左側面板中，選取「GitLab」GitLab做為來源供應商。
在「設定連線」部分，輸入下列資訊：
1. 「Region」(區域)：選取連線的區域。
  
  注意： 您必須指定區域。連結無法在全球範圍內存在。
2. 名稱：輸入連線名稱。
在「主機詳細資料」部分，選取或輸入下列資訊：
1. GitLab 提供者：選取「自行管理的 GitLab Enterprise Edition」做為提供者。
2. 主機網址：輸入連線的主機網址。例如：https://my-gle-server.net。
3. CA 憑證：按一下「瀏覽」上傳自簽憑證。
  
  注意： 憑證大小不得超過 10 KB，且應為 PEM 格式 (.pem、.cer 或 .crt)。如果這個部分留空，系統會改用預設憑證集。
4. 在「連線類型」下方，選取下列其中一個選項：
  1. 公開網際網路：如果可透過公開網際網路存取執行個體，請選取這個選項。
  2. 私人網路存取權：如果執行個體是託管在私人網路中，請選取這個選項。
  3. 在「服務目錄服務」下方，選取服務地點：
    - 在「your-project」專案中
    - 在其他專案中
    - 手動輸入
    1. 如果選取「In another project」(位在其他專案) 或「Enter manually」(手動輸入)，請輸入下列資訊：
      - 專案：輸入或從下拉式選單中選取專案 ID。 Google Cloud
      - 區域：這個欄位會預先選取連線區域。服務指定的區域必須與連線關聯的區域相符。
    2. 命名空間：選取服務的命名空間。
    3. 服務：選取命名空間中的服務名稱。
在「Personal access tokens」部分，輸入下列資訊：
1. API 存取權杖：輸入具有 api 範圍存取權的權杖。這個權杖用於連結及取消連結存放區。
2. 讀取 API 存取權杖：輸入具有 read_api 範圍存取權的權杖。Cloud Build 觸發條件會使用這個權杖存取存放區中的原始碼。
按一下「連線」。

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

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

gcloud

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

將權杖儲存在 Secret Manager。

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

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

如果將密鑰儲存在與建立主機連線時使用的專案不同的專案中，請輸入下列指令，授予專案 Cloud Build 服務代理的存取權： Google Cloud

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。

操作步驟如下：

輸入下列指令，建立 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 密鑰值的密鑰名稱。
WEBHOOK_SECRET_VALUE：網路鉤子密鑰的值。
PROJECT_NUMBER：您的 Google Cloud 專案編號。您可以在 Google Cloud 控制台的「歡迎」頁面中找到專案編號，也可以執行下列指令：
```
gcloud projects describe PROJECT_ID --format='value(projectNumber)'
```
REGION：連線的區域。
CONNECTION_NAME：Cloud Build 中 GitLab Enterprise Edition 主機連線的名稱。
URI：連線的 URI，例如 https://my-gitlab-enterprise-server.net。

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

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

如果 GitLab Enterprise Edition 存取權杖過期，Cloud Build 主機連線就會與 GitLab Enterprise Edition 存放區中斷連線。因此，在下列情況下，您會看到錯誤訊息：

嘗試連結 GitLab Enterprise Edition 存放區與 Cloud Build 連線時，系統會顯示 Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection 訊息。
在「Triggers」(觸發條件) 頁面中，按一下「Run」(執行) 後，系統會開啟「Run trigger」(執行觸發條件) 頁面，並顯示 Failed to list branches. You can still enter one manually 訊息。

如要輪替連線的舊權杖或過期權杖，請按照下列步驟操作：

找出與主機連線相關聯的密鑰：
1. 執行下列指令：
```
gcloud builds connections describe CONNECTION_PATH --region=REGION
```
  其中：
  - CONNECTION_PATH 是 Cloud Build 中 GitLab Enterprise Edition 主機連線的路徑，格式為 projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME。
  - REGION 是連線的區域。
2. 在指令輸出中，找出使用者權杖欄位的值。readAuthorizerCredential.userTokenSecretVersion 顯示權杖的 Secret Manager 名稱，read_api 並顯示權杖的 Secret Manager 名稱。authorizerCredential.userTokenSecretVersion api 這些名稱會以 Secret 形式儲存在 Secret Manager 中。
在 GitLab Enterprise Edition 中輪替每個存取權杖：
1. 前往連結至 Cloud Build 主機連線的 GitLab Enterprise Edition 存放區。
2. 請按照 GitLab 說明文件中的操作說明輪替存取權杖。輪替權杖時，GitLab Enterprise Edition 會建立具有新憑證的新權杖，並使舊版權杖失效。輪替後的權杖與原始權杖的權限和範圍相同。
3. 複製輪替後權杖的 ID。
為每個權杖建立新的密鑰版本：
1. 在 Google Cloud 控制台中開啟「Secret Manager」頁面：
  
  開啟 Secret Manager 頁面
2. 針對您輪替的每個符記，找出您在步驟 1 中識別的密碼名稱，然後按一下「動作」，再按一下「新增版本」。
  
  注意： 如果在「密鑰」視窗中找不到密鑰，請選取「區域性密鑰」分頁，並在「區域性密鑰」視窗中尋找密鑰。
3. 在「新增版本」視窗中，輸入輪替權杖的 ID，然後按一下「新增版本」。

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

後續步驟

瞭解如何連結 GitLab Enterprise Edition 存放區。
瞭解如何在 GitLab 管道中使用 Google 管理的 CI/CD 元件，建構工作負載並部署至 Google Cloud 。請參閱 GitLab 上的 Google Cloud。

連結至 GitLab Enterprise Edition 主機 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

主機需求

必要 IAM 權限

連線至 GitLab Enterprise Edition 主機

控制台

gcloud

Terraform

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

後續步驟

連結至 GitLab Enterprise Edition 主機