GitLab

将 GitLab 仓库连接到 Mintlify，实现自动化文档部署、合并请求预览和持续同步。

Mintlify 使用访问令牌和 webhook 在 GitLab 与 Mintlify 之间进行身份验证并同步变更。

• Mintlify 使用访问令牌从 GitLab 拉取信息。
• GitLab 使用 webhook 在你进行变更时通知 Mintlify，从而为合并请求启用预览部署。

​

设置连接

当你首次打开 Git Settings 时，设置向导将引导你完成 GitLab 存储库的连接。

1. 选择 GitLab 作为提供商

   在 Git Settings 页面，选择 Connect to GitLab 并点击 Continue。

2. 下载你的内容

   如果你在入门引导过程中跳过了 Git 提供商连接，你的文档存储在 Mintlify 托管的存储库中。在继续之前，请下载你的内容作为备份。

3. 查找项目 ID

   在你的 GitLab 项目中，依次进入 Settings > General，找到 Project ID。

   
4. 生成访问令牌

   前往 Settings > Access Tokens，选择 Add new token。

   按以下设置配置令牌：

   • Name：Mintlify
   • Role：Maintainer（私有存储库必需）
   • Scopes：api 和 read_api

   点击 Create project access token 并复制该令牌。

   如果无法使用 Project Access Tokens，可改用 Personal Access Token。请注意，Personal Access Token 会过期，需要定期更新。

   
5. 连接你的存储库

   在 Mintlify 控制台 中填写以下字段：

   • Project ID：你的 GitLab 项目 ID。
   • Access Token：你刚刚生成的访问令牌。
   • Branch：用于部署文档的分支。
   • Subdirectory（可选）：如果你使用的是 monorepo 且文档不在存储库根目录下，请输入文档目录的相对路径。
   • Self-hosted instance URL（可选）：如果你使用自托管的 GitLab 实例，请输入你的 GitLab 实例的主机 URL（例如 https://gitlab.your-domain.com）。你的实例必须可公开访问，以便 Mintlify 能够连接。

   点击 Save Changes。

   

​

更新现有连接

要在初始设置后修改你的 GitLab 连接设置，请前往 Git Settings 直接更新项目 ID、访问令牌、分支或实例 URL。

​

重新验证 Git 设置

如果你的部署出现异常情况（例如缺少分支选项或配置过时），可以强制 Mintlify 刷新你的 Git 源。

1. 前往 Git Settings

   前往控制台中的 Git Settings。

2. 重新验证设置

   点击 GitLab 设置卡片右上角的绿色 Active 徽章以重新验证你的 Git 源。重新验证完成后会显示成功提示，如果配置需要检查则会显示错误提示。

​

创建 webhook

Webhook 会在你推送更改时通知 Mintlify，以便自动触发部署。

1. 添加新 webhook

   1. 在 GitLab 中，依次前往 Settings > Webhooks。
   2. 点击 Add new webhook。

   
2. 设置 URL 和 webhook

   将该 webhook 命名为 Mintlify。

   在 URL 字段中，输入端点 https://leaves.mintlify.com/gitlab-webhook。

3. 获取 webtoken

   在 Mintlify 控制台中，点击 Show Webtoken，然后复制该 webtoken。

   
4. 粘贴 webtoken

   在 GitLab 中，将来自 Mintlify 控制台的 webtoken 粘贴到 Secret token 字段中。

5. 选择事件

   选择以下事件来触发该 webhook：

   • Push events（All branches）
   • Merge requests events
6. 验证 webhook

   配置 webhook 后，你应该看到以下设置：

   • Name：Mintlify
   • URL：https://leaves.mintlify.com/gitlab-webhook
   • Secret token：来自 Mintlify 控制台的 webtoken
   • Events：Push events（All branches）和 Merge requests events

   添加该 webhook。

   
7. 测试 webhook

   创建 webhook 之后，点击 Test 下拉菜单。点击 Push events 以发送示例负载。如果测试返回 Hook executed successfully: HTTP 200，则说明你已正确配置 webhook。

   

​

自托管 GitLab OAuth

如果你在自己的基础设施上运行 GitLab，可以通过 OAuth 将自托管实例连接到 Mintlify。该连接由工作流和代理使用，用于读取仓库、监听 push 和 merge request 事件，以及创建 merge request。

自托管 GitLab OAuth 目前仅在 Enterprise 套餐中可用。如果你在控制台中没有看到该选项，请联系你的 Mintlify 客户代表。

连接自托管实例分为两个步骤：

1. 在你的 GitLab 实例上注册一个 OAuth 应用。
2. 将应用凭据保存到 Mintlify 控制台中，然后授权连接。

​

在你的 GitLab 实例上注册 OAuth 应用

你可以将 OAuth 应用注册为实例级应用（仅管理员）或群组所有的应用。群组所有的应用通常已经足够，并且不需要管理员权限。

1. 打开应用设置

   以管理员或群组所有者身份登录你的 GitLab 实例。

   • 实例级：进入 Admin Area > Applications，点击 Add new application。
   • 群组所有：打开你的群组，进入 Settings > Applications，点击 Add new application。
2. 配置应用

   使用以下值：

   • Name：Mintlify
   • Redirect URI：https://leaves.mintlify.com/gitlab-oauth/callback
   • Confidential：启用
   • Scopes：api 和 read_api

   保存应用。

3. 复制凭据

   GitLab 会显示 Application ID 和 Secret。立即复制这两个值——secret 只会显示一次。

​

在 Mintlify 控制台保存凭据

1. 打开 Git Settings

   进入 Git Settings，在 GitLab OAuth 部分找到 Self-hosted GitLab 卡片。

2. 输入实例信息

   点击 Connect Self-Hosted GitLab 并填写：

   • GitLab instance URL：你的实例的基础 URL（例如 https://gitlab.your-company.com）。必须以 https:// 或 http:// 开头。
   • OAuth application client ID：上一步的 Application ID。
   • OAuth application client secret：上一步的 Secret。会加密存储，保存后 API 不会再返回该值。

   点击 Save instance。

3. 授权连接

   点击 Authorize self-hosted GitLab。你会被重定向到你的 GitLab 实例以批准 OAuth scope，然后返回控制台。

   授权完成后，展开新的连接以浏览群组并启用单个项目。

​

管理连接

• 添加多个用户：组织中的每位成员都可以在同一个自托管实例上授权各自的 GitLab 账户。点击 Add another GitLab connection 添加更多用户。
• 轮换凭据：要轮换 client secret，请删除已保存的实例并使用新值重新添加。你必须先撤销所有有效的 OAuth 连接。
• 移除实例：在 Self-hosted GitLab 卡片上点击 Remove instance。已连接项目上的现有 webhook 会被移除。

​

要求

• GitLab 实例必须可从 leaves.mintlify.com 访问。Mintlify 无法连接到位于 VPN 或屏蔽我们出口流量的 IP 白名单后面的实例。
• 你需要在每个要连接的 GitLab 项目上至少拥有 Maintainer 角色，以便 Mintlify 安装 webhook。
• 每个 Mintlify 组织只能配置一个自托管实例。