mintlify__docs/zh/deploy/gitlab.mdx

---
title: "GitLab"
description: "连接 GitLab 存储库，实现自动部署和预览构建。"
keywords: ["GitLab 集成", "访问令牌", "合并请求预览"]
---

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

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

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

<Note>
  **必须使用 HTTPS 克隆**：为便于 Mintlify 访问你的存储库，你的 GitLab 项目必须启用 HTTPS 克隆。你可以在 GitLab 中前往项目的 **Settings** > **General** > **Visibility and access controls** 部分进行查看与确认。
</Note>

<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. 完成其他必填配置。
    3. 点击 **保存更改**。
    <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 使我们能够在发生更改时接收事件，从而自动触发部署。

<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>