连接到 GitLab Enterprise Edition 主机

本页介绍如何将 GitLab 企业版 主机连接到 Cloud Build。

准备工作

  • 启用 Cloud Build 和 Secret Manager API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

    启用 API

主机要求

  • 如果您尚未安装 GitLab 企业版服务器实例，请参阅 GitLab 企业版 的安装指南了解相关说明。

    按照说明安装 GitLab 企业版服务器实例时，请注意以下事项：

    • 您必须 将主机配置为处理 HTTPS 协议。不支持使用 HTTP 协议配置的主机。

    • 您必须 使用与用于访问您 主机的网址相同的网址来配置主机 Google Cloud。如需了解详情，请参阅 GitLab 文档，了解如何配置外部网址。

必需的 IAM 权限

如需连接您的 GitLab 企业版主机，请将 Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) 角色授予您的用户账号。

如需向您的用户账号添加所需的角色，请参阅配置对 Cloud Build 资源的访问权限。如需详细了解与 Cloud Build 关联的 IAM 角色，请参阅 IAM 角色和权限。

如果您的 GitLab 企业版实例托管在专用网络中， 请参阅从专用网络中的 GitLab 企业版构建代码库，了解在 连接主机之前所需的其他 IAM 角色。

连接到 GitLab 企业版主机

在为 GitLab 企业版实例创建主机连接之前，您必须在 GitLab 企业版中创建个人访问令牌，方法是完成以下步骤：

  1. 登录您的 GitLab 企业版实例。

  2. 在您的实例的 GitLab 企业版页面上，点击右上角的头像。

  3. 点击修改个人资料 。

  4. 在左侧边栏中，选择访问令牌 。

    您会看到“个人访问令牌”页面。

  5. 创建一个具有 api 范围的访问令牌，用于与代码库建立连接和断开连接。

  6. 创建一个具有 read_api 范围的访问令牌，以确保 Cloud Build 代码库可以访问代码库中的源代码。

控制台

如需将 GitLab 企业版主机连接到 Cloud Build，请执行以下操作：

  1. 在 Google Cloud 控制台中打开代码库页面。

    打开“代码库”页面

    您会看到代码库 页面。

  2. 在页面顶部，选择第 2 代 标签页。

  3. 在顶部栏的项目选择器中，选择您的 Google Cloud 项目。

  4. 点击创建主机连接 ，将新主机连接到 Cloud Build。

  5. 在左侧面板中，选择 GitLab 作为您的来源提供方。

  6. 在配置连接 部分中，输入以下信息：

    • 区域：为您的连接选择一个区域。

    • 名称：输入连接的名称。

  7. 在主机详细信息 部分中，选择或输入以下信息：

    • GitLab 主机：选择 Self-managed GitLab Enterprise Edition。

    • 主机网址：输入连接的主机网址。例如，https://my-gle-server.net。

  8. 可选：如果您想管理用于加密 GitLab 企业版代码库的访问令牌的加密密钥，请前往加密 部分，然后选择 Cloud Key Management Service 密钥。如需了解详情，请参阅 为 Secret Manager 启用客户管理的加密密钥。

  9. 在网络 部分的连接类型 下，选择以下选项之一：

    • 公共互联网：如果您的实例可通过公共互联网访问，请选择此选项。

    • 专用网络：如果您的实例托管在 专用网络上，请选择此选项。然后，配置以下内容：

      1. CA 证书：点击“浏览”以上传您的自签名证书。

      2. 在 Service Directory 服务 下，选择服务的部署位置：

        • 在项目 CURRENT_PROJECT 中
        • 在另一个项目中
        • 手动输入

      3. 请输入以下信息：

        • 项目：如果您选择了在另一个项目中或手动输入，请从下拉菜单中输入或 选择您的 Google Cloud 项目 ID。

        • 区域：此字段会预先选择连接的区域。为服务指定的区域必须与连接关联的区域一致。

        • 命名空间：选择服务的命名空间。

        • 服务：在命名空间中选择服务名称。

  10. 在个人访问令牌 部分中，输入以下信息：

    • API 访问令牌：输入具有 api 范围访问权限的令牌。此令牌用于与代码库建立连接和断开连接。

    • 读取 API 访问令牌：输入具有 read_api 范围 访问权限的令牌。Cloud Build 触发器使用此令牌来访问代码库中的源代码。

  11. 点击连接 。

    点击连接 按钮后，您的个人访问令牌将安全地存储在 Secret Manager 中。连接主机后，Cloud Build 还会代表您创建网络钩子 Secret。您可以在 Secret Manager 页面上查看和管理 Secret。您可以在 Secret Manager 页面上查看和管理您的 Secret。

gcloud

在将 GitLab 企业版主机连接到 Cloud Build 之前，请完成以下步骤来存储您的凭据：

  1. 将令牌存储在 Secret Manager 中。

  2. 在 Secret Manager 中创建网络钩子 Secret，方法是运行以下命令：

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

  3. 如果您将 Secret 存储在不同于计划用于创建主机连接的项目中，请输入以下命令，以向您的项目授予对 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 企业版主机连接到 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 中连接的名称。
    • HOST_URI 是 GitLab 企业版实例的 URI。例如，https://my-gle-server.net。
    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • REGION 是连接的 区域。
    • API_TOKEN 是具有 api 范围的令牌的名称。
    • READ_TOKEN 是具有 read_api 范围的令牌的名称。
    • SECRET_VERSION 是 Secret 的版本。
    • WEBHOOK_SECRET 是您的网络钩子 Secret。

您已成功创建 GitLab 企业版连接。

Terraform

您可以使用 Terraform 将 GitLab 企业版主机连接到 Cloud Build。如需详细了解 Terraform，请参阅 Google Cloud。

在以下示例中，代码段执行以下操作：

  • 为资源配置 Google Cloud Terraform 提供程序
  • 创建一个 Secret 来存储您的 GitLab 企业版个人访问令牌
  • 向 Cloud Build 服务代理授予访问 Secret 所需的权限

  • 创建 GitLab 企业版连接

    // 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：包含网络钩子 Secret 值的 Secret 名称。
  • WEBHOOK_SECRET_VALUE：网络钩子 Secret 的值。

  • PROJECT_NUMBER：您的 Google Cloud 项目 编号。您可以在 控制台 的欢迎页面上，或通过运行以下命令来查找项目编号： Google Cloud 

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

  • REGION：连接的区域 。

  • CONNECTION_NAME：Cloud Build 中 GitLab 企业版主机连接的名称。

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

您已成功创建 GitLab 企业版连接。

轮替旧的或过期的 GitLab 企业版访问令牌

如果您的 GitLab 企业版访问令牌过期，则 Cloud Build 主机连接会与 GitLab 企业版代码库断开连接。因此，在以下情况下，您会看到错误：

  • 当您尝试关联 GitLab 企业版代码库 Cloud Build 连接时，系统会显示 Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection 消息。

  • 在触发器 页面上，当您点击运行 时，运行触发器 页面 会打开并显示Failed to list branches. You can still enter one manually 消息。

如需轮替连接的旧令牌或过期令牌，请执行以下操作：

  1. 查找与主机连接关联的 Secret：

    1. 运行以下命令：

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      其中：

      • CONNECTION_PATH 是 Cloud Build 中 GitLab 企业版 主机连接的路径，格式为 projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME。
      • REGION 是连接的 区域。

    2. 在命令的输出中，查找用户令牌字段的值。readAuthorizerCredential.userTokenSecretVersion 显示 read_api 令牌的 Secret Manager 名称，authorizerCredential.userTokenSecretVersion 显示 api 令牌的 Secret Manager 名称。这些名称作为 Secret 存储在 Secret Manager 中。

  2. 在 GitLab 企业版中轮替每个访问令牌：

    1. 前往与 Cloud Build 主机连接关联的 GitLab 企业版代码库。

    2. 按照 GitLab 文档中的说明 轮替访问令牌。 轮替令牌时，GitLab 企业版会使用新凭据创建新令牌，并使该令牌的先前版本失效。轮替后的令牌具有与原始令牌相同的权限和范围。

    3. 复制轮替后的令牌的 ID。

  3. 为每个令牌创建新的 Secret 版本：

    1. 在 Google Cloud 控制台中打开 Secret Manager 页面：

      打开 Secret Manager 页面

    2. 对于您轮替的每个令牌，找到您在第 1 步中确定的 Secret 名称 ，然后依次点击 操作 和 添加新版本。

    3. 在添加新版本 窗口中，输入轮替后的令牌的 ID，然后点击添加新版本 。

如需了解详情，请参阅 GitLab 企业版文档中的访问令牌过期。

后续步骤