#GitLab Connector

GitLab Connector 是一个专用连接器，可用于连接 GitLab Server（包括 GitLab.com 和自托管实例）。

您可以使用 GitLab Connector 在 CI/CD 流水线中安全地克隆私有仓库，使用 GitLab CLI（glab）进行高级操作，或在容器化工作负载中使用自定义 CLI 工具与 GitLab 交互，而无需直接处理凭据。

此外，您可以集中管理跨命名空间的 GitLab 访问配置，避免在每个命名空间中重复配置 GitLab 凭据。

注意：

• GitLab Connector 支持 GitLab.com 和自托管 GitLab 实例。
• GitLab Connector 支持使用 CLI 工具（Git CLI、GitLab CLI 以及自定义 CLI 工具）与 GitLab 交互。

本文档将介绍：

• GitLab 服务器的要求
• 如何基于 GitLab connectorclass 创建 GitLab Connector
• GitLab Connector 的代理及配置能力

#GitLab 服务器和 GitLab CLI (glab) 的要求

要访问的 GitLab 服务器必须满足以下条件：

1. 必须支持 HTTP/HTTPS 传输协议，并且仅兼容 Git 的“smart HTTP”协议模式。该模式是现代 Git 服务器的标准实现，支持高效的数据传输和认证机制。

2. 对于使用 GitLab CLI (glab) 进行的 GitLab API 操作，GitLab 服务器必须满足 glab CLI 的版本要求。详情请参见：GitLab CLI (glab) 版本要求

#基于 GitLab ConnectorClass 创建 GitLab Connector

#快速开始

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth
    secretRef:
      name: gitlab-secret

#spec.connectorClassName

固定值 gitlab。

#描述

您可以通过 annotations 字段为 GitLab Connector 添加描述信息。

• cpaas.io/description：GitLab Connector 的描述信息。

例如：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
  annotations:
    cpaas.io/description: "连接到 GitLab 以访问团队仓库"

#地址

spec.address 指定 GitLab 服务器的访问地址。

重要：此地址用于仓库克隆，不是 GitLab 服务器的 API 地址。使用 GitLab CLI (glab) 时，连接器会自动在该地址后追加 /api/v4 构造 API 地址。

示例：

• GitLab.com: https://gitlab.com
• 自托管实例: https://gitlab.example.com

#认证

GitLab Connector 支持以下认证类型：

• patAuth：私有访问令牌认证（可选），对应的 Secret 类型为 connectors.cpaas.io/gitlab-pat-auth

#使用私有访问令牌认证

私有访问令牌（PAT）是 GitLab 推荐的认证方式，提供细粒度访问控制，且可在不更改密码的情况下轻松撤销。

例如：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth
    secretRef:
      name: gitlab-secret

您需要在相同命名空间中创建一个 Secret，例如：

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
type: connectors.cpaas.io/gitlab-pat-auth
stringData:
  token: glpat-xxxxxxxxxxxxxxxxxxxx  # 您的 GitLab 私有访问令牌

注意：Secret 类型必须为 connectors.cpaas.io/gitlab-pat-auth。

#创建 GitLab 私有访问令牌

关于如何在 GitLab 中创建个人访问令牌的详细说明，请参阅官方文档：{your-gitlab-server}/help/user/profile/personal_access_tokens.md#create-a-personal-access-token

必需的令牌权限范围：

创建令牌时，请根据需要选择以下权限范围：

• read_repository：克隆仓库必需
• write_repository：如果需要推送变更，则必需
• api：GitLab API 操作必需，例如列出项目、分支、合并请求等

安全最佳实践：

为安全起见，建议创建权限最小化的令牌。当需要额外权限时，创建多个权限更高的 Connector，并通过命名空间隔离控制用户访问。

#无需认证使用

如果 GitLab 服务器不需要认证（公共仓库），可以省略 secretRef 字段：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth

#代理及配置

为了让客户端访问 GitLab 服务器时无需直接处理凭据，GitLab ConnectorClass 提供了一个代理服务器，自动注入认证信息。

有权限访问该连接器的客户端可以通过此代理服务器访问 GitLab，无需在客户端配置凭据。

为简化使用，GitLab ConnectorClass 提供了可通过 CSI Driver 挂载到 Pod 的配置文件。在 Pod 中执行 Git CLI、GitLab CLI (glab) 或自定义 CLI 操作时，这些配置会自动将请求路由到代理服务。

#代理地址

创建 GitLab Connector 时，系统会自动创建一个 Service 用于代理访问 GitLab 仓库。

系统会将代理地址记录在 status.proxy.httpAddress 字段。

例如：

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  # . . .
status:
  conditions:
  # . . .
  proxy:
    httpAddress:
      url: http://c-gitlab-demo.default.svc.cluster.local

#配置

GitLab Connector 提供以下配置：

• gitconfig：用于 Git CLI 操作的 Git 配置文件
• gitlabconfig：用于 GitLab CLI (glab) 操作的配置文件

连接器还继承了 connectors-csi 的系统内置配置，详情见：Connectors 系统内置配置

#gitconfig

Git CLI 操作的 Git 配置文件。

• 提供 .gitconfig 文件，将 GitLab 服务器地址重写为代理地址
• 配合 connectors-csi-driver 使用时，该文件挂载到 Pod 中
• 使访问 GitLab 服务器时通过代理，无需在客户端配置凭据

Pod 中生成的 .gitconfig 文件示例：

[http]
    extraHeader = Authorization: Basic OmV5Smhixxxxxxxxx==
[url "http://c-gitlab-demo.default.svc"]
    insteadOf = https://gitlab.com

工作原理：

1. [http] 部分添加了带有 Kubernetes API 服务器令牌的 Authorization 头（用于请求 GitLab Connector 代理服务的临时令牌）
2. [url] 部分将 GitLab 服务器地址重写为代理服务地址
3. Git CLI 执行操作时自动使用这些设置

使用方法：

在 Pod 中使用 gitconfig 配置：

1. 通过 CSI Driver 挂载配置，设置 configuration.names: "gitconfig"
2. 将 .gitconfig 文件复制到用户主目录（通常为 /root/）
3. 设置 .gitconfig 文件权限为 644
4. Git CLI 会自动使用该配置进行所有操作

示例 CSI 卷配置：

volumes:
- name: gitconfig
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "gitlab-demo"
      configuration.names: "gitconfig"

完整使用示例见：快速开始指南

#gitlabconfig

GitLab CLI (glab) 操作的配置文件。

• 提供 GitLab CLI (glab) 的 config.yml 配置文件
• 包含 GitLab 服务器信息、认证令牌和 API 端点
• 使 glab 命令无需手动配置即可使用

Pod 中生成的配置文件示例：

git_protocol: http
host: c-gitlab-demo.default.svc.cluster.local
no_prompt: true
telemetry: false
hosts:
  c-gitlab-demo.default.svc.cluster.local:
    token: k8s-api-token-xxxxxxxx
    container_registry_domains: c-gitlab-demo.default.svc.cluster.local,c-gitlab-demo.default.svc.cluster.local:443,registry.c-gitlab-demo.default.svc.cluster.local
    api_host: c-gitlab-demo.default.svc.cluster.local
    git_protocol: http
    api_protocol: http
    user: any-user

工作原理：

1. 配置指示 glab 使用代理服务
2. 令牌由 Kubernetes API 服务器提供（用于请求 GitLab Connector 代理服务的临时令牌）
3. HTTP 和 API 协议均配置为使用代理，代理会在后端请求中注入认证信息

使用方法：

在 Pod 中使用 gitlabconfig 配置：

1. 通过 CSI Driver 挂载配置，设置 configuration.names: "gitlabconfig"
2. 将 config.yml 文件复制到 ~/.config/glab-cli/
3. 设置文件权限为 600 以保证安全
4. GitLab CLI (glab) 会自动使用该配置进行所有操作

示例 CSI 卷配置：

volumes:
- name: gitlab-config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connector.name: "gitlab-demo"
      configuration.names: "gitlabconfig"

完整 glab 命令使用示例见：使用 GitLab CLI (glab)

#多配置同时使用

您可以在同一个 Pod 中挂载多个配置，configuration.names 字段用逗号分隔：

volumeAttributes:
  connector.name: "gitlab-demo"
  configuration.names: "gitlabconfig,gitconfig"

这样可以在同一个 Pod 中同时使用 Git CLI 和 GitLab CLI (glab) 操作。实用示例见：

• 使用 GitLab CLI (glab) - 使用 glab 克隆仓库

#使用系统内置配置

挂载 gitlab 连接器时，以下内置配置文件可用：

• context.token：GitLab 认证的私有访问令牌
• connector.status.proxyAddress：代理服务地址

这些文件适用于需要直接访问认证令牌或代理地址的自定义集成或 CLI 工具。

完整示例见：使用 Reviewdog 与 GitLab Connector

更多系统内置配置详情见：Connectors-CSI 内置配置

#延伸阅读

• 快速开始指南 - GitLab Connector 入门
• 使用 GitLab CLI (glab) - 学习如何使用 glab 配合连接器
• 使用 Reviewdog - 学习如何使用 reviewdog 等自定义 CLI 工具与 GitLab 交互
• CI/CD 集成 - 在 CI/CD 流水线中使用