# GitLab (/zh/deploy/gitlab)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1228 · updated: 2026-07-30 -->

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

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

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

当你首次打开 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 时，设置向导将引导你完成 GitLab 存储库的连接。

<Steps>
  <Step title="选择 GitLab 作为提供商">
    在 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 页面，选择 **Connect to GitLab** 并点击 **Continue**。
  </Step>

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

  <Step title="查找项目 ID">
    在你的 GitLab 项目中，依次进入 **Settings** > **General**，找到 **Project ID**。

    <Frame>
      <img src="/_assets/bb826ce16241f19d1ddc499f4b5fc82278e2567a3a38200e43e60f87899b2187" 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="/_assets/f6d06d9e88e7fab6ae076e532d8856ced528e236d2537adf9fbd8bf2cc056477" alt="GitLab 控制台的 Access tokens 页面，为 Mintlify 配置的设置已高亮显示。" />
    </Frame>
  </Step>

  <Step title="连接你的存储库">
    在 [Mintlify 控制台](https://app.mintlify.com/settings/deployment/git-settings) 中填写以下字段：

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

    点击 **Save Changes**。

    <Frame>
      <img src="/_assets/e692151369f14271f818eab32938733c6dacb4d1294956400454d0f9465cf537" alt="Mintlify 控制台 Git Settings 页面中的 GitLab 配置面板。" className="block dark:hidden" />

      <img src="/_assets/c289e2dbc4fb9b0f76602dd21ea9533ae4f8dffcbed460b26b86f28b8cccb02c" alt="Mintlify 控制台 Git Settings 页面中的 GitLab 配置面板。" className="hidden dark:block" />
    </Frame>
  </Step>
</Steps>

<div id="update-an-existing-connection">
  ## 更新现有连接 [#更新现有连接]
</div>

要在初始设置后修改你的 GitLab 连接设置，请前往 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) 直接更新项目 ID、访问令牌、分支或实例 URL。

## 重新验证 Git 设置 [#重新验证-git-设置]

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

<Steps>
  <Step title="前往 Git Settings">
    前往控制台中的 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings)。
  </Step>

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

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

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

<Steps>
  <Step title="添加新 webhook">
    1. 在 GitLab 中，依次前往 **Settings** > **Webhooks**。
    2. 点击 **Add new webhook**。

    <Frame>
      <img src="/_assets/0e4ee3d9ee09b3a73c8c65d831bbdd945cf3b468f6948c5d1c8f2d5060c8f0ae" 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="/_assets/abf6566843c168dbd23aed587f44ab8fcd9f0da83bb56888073fadae3de95463" alt="Mintlify 控制台中 GitLab 连接的截图。" className="block dark:hidden" />

      <img src="/_assets/8ee3868d172d45ee30cef080d04431979c6b5d660f552915022cb03d0546af8a" 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="/_assets/492254d1ca23ea8f27591b7ee98a8a3ef3104f844029cecc6f1e992b9b75a30f" alt="GitLab 控制台中的 Webhook 页面。为 Mintlify 配置的设置被高亮显示。" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="/_assets/748a9164b8483a9bc811a0173638a0e62269da2fe1b72419fe519a5d306b02a6" alt="GitLab Webhooks 页面截图。'Test' 菜单中的 'Push events' 菜单项被高亮显示。" />
    </Frame>
  </Step>
</Steps>