mintlify__docs/zh/deploy/gitlab.mdx

---
title: "GitLab"
description: "将 GitLab 仓库连接到 Mintlify，实现自动化文档部署、合并请求预览和持续同步。"
keywords: ["GitLab 集成", "访问令牌", "合并请求预览", "自托管", "实例"]
---

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

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

<div id="set-up-the-connection">
  ## 设置连接
</div>

<Steps>
  <Step title="查找项目 ID">
    在你的 GitLab 项目中，依次进入 **Settings** > **General**，找到 **Project ID**。
    <Frame>
      <img src="/images/gitlab/gitlab-project-id.png" alt="GitLab 控制台的 General Settings 页面，Project ID 已高亮显示。" />
    </Frame>
  </Step>
  <Step title="生成访问令牌">
    前往 **Settings** > **Access Tokens**，选择 **Add new token**。
    
    按以下设置配置令牌：
    - **Name**：Mintlify
    - **Role**：Maintainer（私有存储库必需）
    - **Scopes**：`api` 和 `read_api`
    
    点击 **Create project access token** 并复制该令牌。

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

    <Frame>
      <img src="/images/gitlab/gitlab-project-access-token.png" alt="GitLab 控制台的 Access tokens 页面，为 Mintlify 配置的设置已高亮显示。" />
    </Frame>

  </Step>
  <Step title="设置连接">
    在 [Mintlify 控制台](https://dashboard.mintlify.com/settings/deployment/git-settings)：
    1. 输入你的项目 ID 和访问令牌。
    2. 如果你使用的是 monorepo 且文档不在存储库根目录下，请启用 **Set up as monorepo** 开关并输入文档目录的相对路径。
    3. 如果你使用自托管的 GitLab 实例，请启用 **Set up as self-hosted** 选项并输入你的 GitLab 实例的主机 URL（例如 `https://gitlab.your-domain.com`）。你的实例必须可公开访问，以便 Mintlify 能够连接。
    4. 选择用于部署文档的分支。
    5. 点击 **Save Changes**。
    <Frame>
      <img src="/images/gitlab/gitlab-config-light.png" alt="Mintlify 控制台 Git Settings 页面中的 GitLab 配置面板。" className="block dark:hidden" />
      <img src="/images/gitlab/gitlab-config-dark.png" alt="Mintlify 控制台 Git Settings 页面中的 GitLab 配置面板。" className="hidden dark:block" />
    </Frame>
  </Step>
</Steps>

<div id="create-the-webhook">
  ## 创建 webhook
</div>

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

<Steps>
  <Step title="添加新 webhook">
  1. 在 GitLab 中，依次前往 **Settings** > **Webhooks**。
  2. 点击 **Add new webhook**。
    <Frame>
      <img src="/images/gitlab/gitlab-webhook.png" alt="GitLab 控制台中 Webhooks 页面截图。" />
    </Frame>
  </Step>
  <Step title="设置 URL 和 webhook">
    将该 webhook 命名为 **Mintlify**。

    在 **URL** 字段中，输入端点 `https://leaves.mintlify.com/gitlab-webhook`。
  </Step>
  <Step title="获取 webtoken">
    在 Mintlify 控制台中，点击 **Show Webtoken**，然后复制该 webtoken。
    <Frame>
      <img src="/images/gitlab/show-webtoken-light.png" alt="Mintlify 控制台中 GitLab 连接的截图。" className="block dark:hidden" />
      <img src="/images/gitlab/show-webtoken-dark.png" alt="Mintlify 控制台中 GitLab 连接的截图。" className="hidden dark:block" />
    </Frame>
  </Step>
  <Step title="粘贴 webtoken">
    在 GitLab 中，将来自 Mintlify 控制台的 webtoken 粘贴到 **Secret token** 字段中。
  </Step>
  <Step title="选择事件">
    选择以下事件来触发该 webhook：
    - **Push events**（All branches）
    - **Merge requests events**
  </Step>
  <Step title="验证 webhook">
    配置 webhook 后，你应该看到以下设置：
    
    - **Name**：Mintlify
    - **URL**：`https://leaves.mintlify.com/gitlab-webhook`
    - **Secret token**：来自 Mintlify 控制台的 webtoken
    - **Events**：**Push events**（All branches）和 **Merge requests events**

    添加该 webhook。

    <Frame>
      <img src="/images/gitlab/gitlab-project-webtoken.png" alt="GitLab 控制台中的 Webhook 页面。为 Mintlify 配置的设置被高亮显示。" />
    </Frame>
  </Step>
  <Step title="测试 webhook">
    创建 webhook 之后，点击 **Test** 下拉菜单。点击 **Push events** 以发送示例负载。如果测试返回 `Hook executed successfully: HTTP 200`，则说明你已正确配置 webhook。

    <Frame>
      <img src="/images/gitlab/gitlab-project-webtoken-test.png" alt="GitLab Webhooks 页面截图。'Test' 菜单中的 'Push events' 菜单项被高亮显示。" />
    </Frame>

  </Step>
</Steps>