连接到 GitLab 主机

本页介绍了如何将 GitLab 主机连接到 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 主机

在为 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. 在配置连接部分中，输入以下信息：

    1. 区域：为连接选择一个区域。

    2. 名称：输入连接的名称。

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

    1. GitLab 提供程序：选择 GitLab.com 作为提供程序。

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

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

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

  9. 点击连接。

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

您现在已成功创建 GitLab 连接。

gcloud

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

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

  2. 运行以下命令，在 Secret Manager 中创建 webhook Secret：

     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 是具有 api 范围的令牌的名称。
    • READ_TOKEN 是具有 read_api 范围的令牌的名称。
    • SECRET_VERSION 是相应 Secret 的版本。
    • WEBHOOK_SECRET 是您的 Webhook Secret。

您现在已成功创建 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. 查找与主机连接关联的密钥：

    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 名称，然后依次点击 Actions（操作）和 Add new version（添加新版本）。

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

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

后续步骤