GitLab

GitLab 连接器适合把单个项目的 MR、Issue 和可选默认分支文件引入企业知识检索。它不是完整代码托管权限同步器；上线前应先确认 token 范围、项目范围和艾维斯访问群组。

适用场景

场景	建议
研发问答	索引单个项目的 MR 与 Issue description，帮助 Agent 回答项目背景和决策问题。
代码说明检索	仅在确认部署级代码文件开关、文件范围和资源成本后启用默认分支文件索引。
多项目知识库	每个项目使用独立连接器和独立访问群组，避免跨项目内容泄漏。
受限项目	使用最小权限 token，并用艾维斯私有群组限制搜索受众。

索引内容

GitLab 连接器以项目 Owner 与项目名称标识一个目标项目。当前管理表单不提供全群组或多项目模式。

GitLab 数据	索引行为
Merge request	启用后，每个 MR 会成为一个文档。标题是文档标识，description 是可搜索文本。状态、类型、作者、创建时间与更新时间会被保留。评论、approval、diff 与 commit 内容不会被索引。
Issue 与 work item	启用后，每个返回的 issue 会成为一个文档。标题是文档标识，description 是可搜索文本。状态、返回的类型、作者、创建时间与更新时间会被保留。评论不会被索引。
仓库文件	仓库文件索引由部署级 `GITLAB_CONNECTOR_INCLUDE_CODE_FILES` 控制，而不是管理表单；只有该值为 `true` 时才启用。启用后，连接器会遍历当前默认分支，并尝试索引所有未命中内置路径排除规则的 blob。README 与源码都会被包含；此范围比 GitHub 的仅文档策略更宽。
分支与链接	没有分支选择器。文件内容与 blob 链接使用项目当前默认分支。Merge request 与 issue 属于整个项目，不按分支筛选。
文件解码	文件字节先按 UTF-8 解码，Unicode 解码失败时再按 Latin-1 解码。此实现没有连接器级扩展名 allowlist 或文件大小 gate，因此启用代码文件前，需要在目标项目中测试二进制、生成、vendor 与大文件行为。

连接器不会为项目元数据、commit、wiki 页面、pipeline、release、snippet 或仓库目录单独创建文档。

前置条件

确认准确的 GitLab 根 URL，例如 https://gitlab.com 或自托管实例的 HTTPS 根地址。
创建专用 GitLab access token，使其能打开目标项目，并读取已启用的 merge-request、issue、repository-tree 与 file API。
当前连接器凭据包含 GitLab URL 与一个 access-token 字段，不包含 application ID、application secret、OAuth callback 或 private-key 字段；不要把 application secret 填入 token 字段。
记录准确的项目 owner namespace 与项目名称。当前表单每个连接器只配置一个项目。
允许艾维斯 worker 访问 GitLab 主机，并允许用户浏览器访问同一主机以打开源链接。
向部署运维人员确认是否已启用 GITLAB_CONNECTOR_INCLUDE_CODE_FILES。应把它视为部署级内容决策，而不是单连接器复选框。

配置数据获取入口

配置数据	获取方式
GitLab URL	使用 GitLab 实例根地址，例如 `https://gitlab.com` 或自托管实例根地址；不要复制项目详情页。
GitLab access token	在 GitLab 用户设置中创建 personal access token。可参考 GitLab Docs：Personal access tokens 和 Access token scopes。
项目 Owner / namespace	从项目 URL 中取项目名称之前的 namespace，例如 `group/subgroup/project` 中的 `group/subgroup`。可参考 GitLab Docs：Namespaces。
项目名称	从项目 URL 的最后一段获取；也可用 GitLab Projects API 验证 token 是否能读取项目。
MR / Issue API 可读性	用目标 token 调用 GitLab 项目 API、merge-request API 和 issue API，确认所选内容类型可读。

凭据

方式	艾维斯凭据值	认证行为
GitLab access token	`gitlab_url: <GITLAB_URL>`、`gitlab_access_token: <GITLAB_ACCESS_TOKEN>`	艾维斯会在配置的 URL 初始化 GitLab API 客户端，并把 token 作为 private token 传入。同一凭据用于读取全部选定内容。

请使用 GitLab 实例根 URL，而不是项目页面。当前 schema 没有暴露独立的 GitLab application 或 OAuth 凭据流程。不同 token 类型与 GitLab 部署使用的准确 scope 标签可能不同；应验证已启用内容类型实际使用的项目 API 访问能力。

在艾维斯中配置

在管理后台打开连接器，选择 GitLab。先创建或选择 GitLab 凭据，再填写单个项目的 owner、项目名称和内容类型。

字段	填写方式	说明
GitLab URL	例如 `https://gitlab.com` 或自托管实例根地址	不要填写具体项目页面。
GitLab access token	粘贴专用 token	用于访问目标 GitLab API。保存后通常不会明文展示。
项目 Owner	例如 `alephant` 或 `group/subgroup`	填写 namespace，不包含项目名。
项目名称	例如 `product-api`	当前表单每个连接器只支持一个项目。
包含 MR	默认开启	只索引 MR 标题和 description，不索引评论或 diff。
包含 Issue	默认开启	只索引 issue 标题和 description，不索引评论。

在管理后台打开连接器，选择 GitLab，并用 GitLab 根 URL 与 access token 创建凭据。
为一个项目填写准确的项目 Owner namespace 与项目名称。
在高级设置中启用或禁用包含 MR与包含 Issue。这些选项只控制 description，不会加入评论、diff 或 commit 内容。
向运维人员确认部署级代码文件设置。连接器页面没有逐项目代码文件控制、分支选择器、扩展名筛选或大小限制。
受限项目内容应选择艾维斯私有群组。仅当每个艾维斯账号都可以搜索此连接器产生的全部 MR、issue 与文件时才使用公开。
设置刷新与清理选项，创建连接器并运行一次索引。

标准管理后台创建的连接器使用 poll（input_type: poll）：GitLab 不在管理后台 isLoadState 列表中。管理表单没有暴露 full/load 控件。因此，每次标准索引都会带时间窗口调用连接器 poll 路径，而不是调用其独立的 load_from_state 方法。

轮询期间，merge request 会按更新时间降序请求，并按轮询起止时间筛选。遇到早于轮询起点的 MR 时，当前实现会从整个轮询 pass 返回；如果同时启用了 MR 与 issue，issue 阶段因此可能被跳过。到达 issue 阶段后，issue 会按更新时间筛选，但当前 API 调用没有明确请求排序，而且遇到第一个早于起点的条目时也会返回。应针对目标 GitLab 版本与内容组合测试增量覆盖。

启用代码文件索引时，每次轮询都会在 MR 与 issue 筛选之前遍历并输出当前默认分支文件集。文件文档以摄取时间作为更新时间；轮询窗口不会用于跳过未变更仓库文件。

权限

GitLab token 决定艾维斯可以摄取哪些项目内容，但此连接器不会把 GitLab 项目成员关系、群组、角色、protected-branch 规则、confidential-issue 访问或逐条目权限同步到艾维斯。当前管理后台访问选择器不把 GitLab 作为自动同步权限源提供。

因此，搜索访问仅由连接器的艾维斯私有群组或公开模式控制。任何能访问连接器的用户都可以搜索 token 产生的全部 MR description、issue description、作者标识与已启用的默认分支文件内容，即使该用户无法在 GitLab 打开源条目。

应使用最小权限 token、每项目一个连接器，并为不得共享内容的受众使用独立艾维斯私有群组。内容被索引后，不要依赖 GitLab confidential 标记、项目角色、protected branch 或源群组隐藏文档。

验证

运行连接器，并确认凭据解析到预期 GitLab 主机和准确 owner/project 路径。
搜索一个已启用 MR 的标题与独特 description，以及一个已启用 issue 或 work item 的标题与 description。
确认 MR 评论、approval、diff、issue 评论与 commit 内容不存在。
禁用代码文件索引时，确认 README 与源码不存在。启用时，搜索默认分支中的一个 README 和一个源码文件，再确认只存在于其他分支的文件不存在。
把一组已知源 issue 与增量轮询结果对账。先启用 MR，观察旧 MR 是否阻止 issue 阶段；再在诊断连接器中关闭 MR，以隔离 issue 循环。加入更新时间混合的 issue，并逐个比较预期 ID。关闭 MR 只能移除 MR 阶段的提前返回，不能保证完整的 issue 增量覆盖。
如果启用了代码文件，请在仓库没有变化时运行两次轮询，确认运维成本与重复文件 upsert 可以接受。同时测试有代表性的二进制、生成、vendor 与大文件。
测试每个已分配艾维斯群组和一个群组外用户，因为搜索时不会重新检查 GitLab 访问权限。

故障排除

症状	检查项
认证失败	替换无效或已过期的 GitLab access token，并确认它属于已配置主机。
找不到项目或访问被拒绝	检查 GitLab 根 URL、准确 owner namespace、准确项目名称、token 项目访问与网络可达性。
只有一个项目被索引	这是预期行为。连接器接受一个 owner/project 组合；其他项目应创建独立连接器和艾维斯访问群组。
Merge request 或 issue 为空	确认对应高级复选框已启用、token 能读取该 API，且连接器状态筛选包含目标条目。只有 description 可搜索。
增量更新的 issue 被遗漏	启用 MR 时，旧 MR 可能在 issue 运行前结束 poll。关闭 MR 只是一种隔离第一次提前返回的诊断方法：issue 调用仍未明确请求排序，并会在首个旧 issue 处返回，因此 issue-only 轮询不能保证完整性。标准管理后台路径没有 full/load 控件。对完整性有严格要求时，应把预期 issue ID 与 GitLab 对账，并在轮询逻辑修复前把缺口视为实现限制。
README 或源码文件缺失	确认部署级 `GITLAB_CONNECTOR_INCLUDE_CODE_FILES` 已准确启用，文件位于当前默认分支且未命中内置排除规则。管理后台没有此设置的复选框。
文件链接指向非预期分支	连接器始终读取当前项目默认分支。请更改 GitLab 项目默认分支或使用其他摄取方式；此连接器没有分支覆盖项。
文件轮询成本异常高	启用代码索引后，每次轮询都会遍历并输出默认分支文件集，不受 MR/issue 轮询窗口限制。应降低刷新频率、缩小项目，或禁用部署级代码文件设置。
二进制或生成内容以文本出现	代码文件模式没有扩展名或大小 allowlist，并会 fallback 到 Latin-1 解码。如果项目文件组合不适合宽范围遍历，请禁用部署设置。
用户可以搜索自己无法在 GitLab 打开的内容	这是预期行为，因为 GitLab 源权限不会同步。使用艾维斯私有群组限制连接器、缩小 token/项目范围，或把项目拆为不同连接器。