Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

连接到 GitLab Enterprise Edition 主机

本页介绍了如何将 GitLab Enterprise Edition 主机连接到 Cloud Build。

准备工作

启用 Cloud Build 和 Secret Manager API（如果尚未启用）。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。了解如何授予角色。
启用 API

主机要求

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

按照说明安装 GitLab Enterprise Edition 服务器实例时，请注意以下事项：
- 您必须配置主机以处理 HTTPS 协议。不支持配置了 HTTP 协议的主机。
- 您必须使用与从 Google Cloud访问主机时所用的网址相同的网址来配置主机。如需了解详情，请参阅有关配置外部网址的 GitLab 文档。

必需的 IAM 权限

如需连接您的 GitLab Enterprise Edition 主机，请将 Cloud Build Connection Admin (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 控制台中打开代码库页面。

打开“代码库”页面

您会看到代码库页面。
选择页面顶部的第 2 代标签页。
在顶部栏的项目选择器中，选择您的 Google Cloud 项目。
点击创建主机连接，将新主机连接到 Cloud Build。
在左侧面板中，选择 GitLab 作为来源提供方。
在配置连接部分中，输入以下信息：
- 区域：为连接选择一个区域。
  
  注意：您必须指定一个区域。您的连接无法在全球范围内存在。
- 名称：输入连接的名称。
在主机详细信息部分，选择或输入以下信息：
- GitLab 主机：选择自行管理的 GitLab Enterprise Edition。
- 主机网址：输入连接的主机网址。例如 https://my-gle-server.net。
可选：如果您想管理用于加密 GitLab Enterprise Edition 代码库的访问令牌的加密密钥，请前往加密部分，然后选择 Cloud Key Management Service 密钥。如需了解详情，请参阅为 Secret Manager 启用客户管理的加密密钥。
在网络部分的连接类型下，选择以下选项之一：
- 公共互联网：如果您的实例可通过公共互联网访问，请选择此选项。
- 专用网络：如果您的实例托管在专用网络上，请选择此选项。然后，配置以下内容：
  1. CA 证书：点击“浏览”上传您的自签名证书。
    
    注意：您的证书大小不得超过 10 KB，并且应采用 PEM 格式（.pem、.cer 或 .crt）。如果此部分留空，则将使用一组默认证书。
  2. 在 Service Directory 服务下，选择服务的位置：
    - 在项目 CURRENT_PROJECT 中
    - 在其他项目中
    - 手动输入
  3. 请输入以下信息：
    - 项目：如果您选择了在另一个项目中或手动输入，请在下拉菜单中输入或选择您的 Google Cloud 项目 ID。
    - 区域：此字段会预先选择连接所在的区域。为服务指定的区域必须与关联的连接的区域一致。
    - 命名空间：选择服务的命名空间。
    - 服务：选择您命名空间中的服务名称。
在个人访问令牌部分中，输入以下信息：
- API 访问令牌：输入具有 api 范围访问权限的令牌。此令牌用于与代码库建立连接和断开连接。
- 读取 API 访问令牌：输入具有 read_api 范围访问权限的令牌。Cloud Build 触发器使用此令牌访问代码库中的源代码。
点击连接。

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

gcloud

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

将令牌存储在 Secret Manager 中。

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

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

如果您将密钥存储在不同于计划用于创建宿主连接的 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。

请完成以下步骤：

输入以下命令以创建 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 是具有 api 范围的令牌的名称。
- READ_TOKEN 是具有 read_api 范围的令牌的名称。
- SECRET_VERSION 是相应 Secret 的版本。
- WEBHOOK_SECRET 是您的 Webhook 密钥。

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

Terraform

您可以使用 Terraform 将 GitLab Enterprise Edition 主机连接到 Cloud Build。详细了解 Terraform on Google Cloud。

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

为 Google Cloud 资源配置 Terraform 提供方
创建用于存储 GitLab Enterprise Edition 个人访问令牌的密文
向 Cloud Build 服务代理授予访问 Secret 的必要权限

创建 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：Webhook 密钥的值。
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 访问令牌

轮换访问令牌，以便 Cloud Build 主机连接能够保持与 GitLab Enterprise Edition 代码库的连接。如果您的 GitLab Enterprise Edition 访问令牌过期，Cloud Build 主机连接将与 GitLab Enterprise Edition 代码库断开连接。发生这种情况时，您无法停用连接或关联代码库，除非您轮换已过期的令牌。此外，在以下情况下，您会看到错误：

相应连接的连接详情页面会显示一条错误消息，指出 Connection is disconnected due to an invalid or expired access token。
如果您尝试将代码库与令牌已过期的连接相关联，则会看到访问令牌无效消息。点击查看连接会进入令牌已过期的连接的连接详情页面。

Cloud Build 可让您通过输入新的令牌值并将其保存在 Secret Manager 中作为这些令牌的最新 Secret 版本来轮换访问令牌。如需轮换访问令牌，请执行以下操作：

在 GitLab Enterprise Edition 中轮换每个访问令牌：
1. 前往与 Cloud Build 主机连接关联的 GitLab Enterprise Edition 代码库。
2. 按照 GitLab 文档中的说明轮换访问令牌。轮换令牌时，GitLab Enterprise Edition 会创建具有新凭据的新令牌，并使该令牌的先前版本失效。轮换后的令牌与原始令牌具有相同的权限和范围。
3. 复制已轮换的令牌的 ID。
在 Cloud Build 中更新访问令牌：
1. 前往相应连接的连接详情页面。
2. 选择更新访问令牌。
3. 在令牌轮换菜单中，在 API 访问令牌和读取访问令牌字段中输入新令牌。
4. （可选）：如果您希望连接始终使用令牌的最新版密钥，请选择更新连接以始终使用最新版本。如果您的连接使用特定的密钥版本号，则取消选中此选项可能会有所帮助。
5. 选择更新以保存更改。
  
  Cloud Build 会将新的访问令牌保存为 Secret Manager 中 Secret 的最新版本。

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

后续步骤

了解如何关联 GitLab Enterprise Edition 代码库。
了解如何在 GitLab 流水线中使用 Google 管理的 CI/CD 组件，将工作负载构建并部署到 Google Cloud 。请参阅 Google Cloud上的 GitLab。

连接到 GitLab Enterprise Edition 主机 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

主机要求

必需的 IAM 权限

连接到 GitLab Enterprise Edition 主机

控制台

gcloud

Terraform

轮换旧的或已过期的 GitLab Enterprise Edition 访问令牌

后续步骤

连接到 GitLab Enterprise Edition 主机