跳到主要内容

GitLab 集成

将您的 GitLab 仓库连接到 ArchiCore 以进行自动分析。

功能​

  • 自托管支持 — 连接 gitlab.com 或您自己的 GitLab 实例
  • 多实例 — 同时连接多个 GitLab 服务器
  • 私有仓库 — 完全访问私有项目
  • 分支选择 — 选择要分析的分支
  • 自动分析 — 推送事件时自动分析
  • 合并请求审查 — 在 MR 上进行 AI 驱动的代码审查

设置​

步骤 1：创建个人访问令牌​

  1. 转到您的 GitLab → 设置 → 访问令牌
  2. 使用以下必需范围创建新令牌：
    • api — 必需，用于完整 API 访问（私有仓库、webhooks、MR 评论）
    • read_repository — 必需，用于读取仓库内容
必需范围

对于私有仓库，api 范围是必需的。没有它，ArchiCore 无法访问私有项目，即使您是仓库所有者或管理员。

  1. 复制令牌（您将不会再次看到它！）

步骤 2：连接 GitLab 实例​

通过 Web 界面：

  1. 转到 ArchiCore → 设置 → 集成
  2. 点击 添加 GitLab
  3. 输入您的 GitLab URL（例如 https://gitlab.com 或 https://gitlab.company.com）
  4. 粘贴您的个人访问令牌
  5. 点击 连接

通过 API：

curl -X POST https://api.archicore.io/api/gitlab/instances \
  -H "Authorization: Bearer 您的_ARCHICORE_令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceUrl": "https://gitlab.company.com",
    "accessToken": "您的_GITLAB_PAT",
    "name": "公司 GitLab"
  }'

步骤 3：连接仓库​

  1. 连接 GitLab 实例后，点击 添加项目
  2. 选择 GitLab 实例
  3. 搜索您的仓库
  4. 选择分支
  5. 点击 连接

自托管 GitLab​

ArchiCore 完全支持自托管 GitLab 实例。

SSL 证书​

如果您的 GitLab 使用自签名证书：

  1. 连接时，启用 "允许自签名证书"
  2. 或在 API 调用中设置 rejectUnauthorizedSSL: false

网络访问​

要使 webhook 工作，您的 GitLab 实例必须能够访问 ArchiCore 的 webhook 端点：

https://api.archicore.io/api/gitlab/webhook

如果 ArchiCore 也是自托管的，请在环境中配置 GITLAB_WEBHOOK_URL。

多实例​

您可以连接多个 GitLab 实例：

  • gitlab.com（公共）
  • gitlab.company.com（公司）
  • gitlab.client.com（客户项目）

每个实例使用自己的凭据单独管理。

Webhooks​

ArchiCore 可以自动创建 webhook 用于：

  • 推送事件 — 推送代码时触发分析
  • 合并请求事件 — 向 MR 添加 AI 审查评论

Webhook 设置​

当您连接启用了"自动分析"的仓库时，会自动创建 webhook。

手动 webhook 配置：

  1. 转到您的 GitLab 项目 → 设置 → Webhooks
  2. 添加 URL：https://api.archicore.io/api/gitlab/webhook
  3. 密钥令牌：（由 ArchiCore 提供）
  4. 启用：推送事件、合并请求事件

API 参考​

列出实例​

GET /api/gitlab/instances

添加实例​

POST /api/gitlab/instances
Content-Type: application/json

{
  "instanceUrl": "https://gitlab.company.com",
  "accessToken": "glpat-xxxxxxxxxxxx",
  "name": "我的 GitLab",
  "rejectUnauthorizedSSL": true
}

列出项目​

GET /api/gitlab/instances/{instanceId}/projects?search=myproject

列出分支​

GET /api/gitlab/instances/{instanceId}/projects/{projectId}/branches

连接仓库​

POST /api/gitlab/repositories/connect
Content-Type: application/json

{
  "instanceId": "uuid",
  "projectId": 123,
  "autoAnalyze": true,
  "analyzeMRs": true,
  "branch": "main"
}

断开仓库连接​

DELETE /api/gitlab/repositories/{repoId}

故障排除​

"无效令牌"​

  • 检查过期 — 确保您的 PAT 未过期
  • 验证范围 — 令牌必须具有 api 和 read_repository 范围
  • 检查 URL — 对于自托管 GitLab，确保 URL 正确（包含 https://）
  • 重新生成令牌 — 如果问题持续，请使用正确的范围创建新令牌

"SSL 证书错误"​

  • 连接时启用"允许自签名证书"
  • 或将您的 CA 证书添加到系统信任存储

"Webhook 未接收事件"​

  • 验证您的 GitLab 是否可以访问 webhook URL
  • 检查 GitLab → 项目 → 设置 → Webhooks → 最近的交付
  • 确保 webhook 密钥匹配

"未找到仓库"​

  • 检查令牌范围 — 对于私有仓库，您的 PAT 必须具有 api 范围。仅 read_api 范围是不够的。
  • 验证令牌权限 — 即使您是仓库管理员或所有者，范围不正确的令牌也无法访问私有项目。
  • 输入完整路径 — 连接时，使用完整的仓库路径（例如 组/子组/项目名称），而不仅仅是项目名称。
  • 检查归档状态 — 已归档的仓库可能不会出现在搜索结果中。
  • 确认正确的实例 — 确保您正在查看正确的 GitLab 服务器（gitlab.com 与自托管）。