mintlify__docs/zh/deploy/gitlab.mdx

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

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

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

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

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

<Steps>
  <Step title="选择 GitLab 作为提供商">
    在 [Git Settings](https://dashboard.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="/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) 中填写以下字段：

    - **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="/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="update-an-existing-connection">
  ## 更新现有连接
</div>

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

## 重新验证 Git 设置

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

<Steps>
  <Step title="前往 Git Settings">
    前往控制台中的 [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings)。
  </Step>
  <Step title="重新验证设置">
    点击 GitLab 设置卡片右上角的绿色 **Active** 徽章以重新验证你的 Git 源。重新验证完成后会显示成功提示，如果配置需要检查则会显示错误提示。
  </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>