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。

​

创建 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。