mintlify__docs/deploy/gitlab.mdx

---
title: "GitLab"
description: "Connect to a GitLab repository for automated deployments and preview builds."
keywords: ["GitLab integration", "access tokens", "merge request previews"]
---

import { RainbowText } from '../components/RainbowText';

We use access tokens and webhooks to authenticate and sync changes between GitLab and Mintlify.

- Mintlify uses access tokens to pull information from GitLab.
- GitLab uses webhooks to notify Mintlify when changes are made, enabling preview deployments for merge requests.

## Set up the connection

<Note>
  **HTTPS cloning required**: Your GitLab project must have HTTPS cloning enabled for Mintlify to access your repository. You can verify this in GitLab by going to your project's **Settings** > **General** > **Visibility and access controls** section.
</Note>

<Steps>
  <Step title="Find your project ID">
    In your GitLab project, navigate to **Settings** > **General** and locate your **Project ID**.
    <Frame>
      <img src="/images/gitlab/gitlab-project-id.png" alt="The General Settings page in the GitLab dashboard. The Project ID is highlighted." />
    </Frame>
  </Step>
  <Step title="Generate an access token">
    Navigate to **Settings** > **Access Tokens** and select **Add new token**.
    
    Configure the token with these settings:
    - **Name**: Mintlify
    - **Role**: Maintainer (required for private repos)
    - **Scopes**: `api` and `read_api`
    
    Click **Create project access token** and copy the token.

    <Note>
      If Project Access Tokens are not available, you can use a Personal Access Token instead. Note that Personal Access Tokens expire and must be updated.
    </Note>

    <Frame>
      <img src="/images/gitlab/gitlab-project-access-token.png" alt="The Access tokens page in the GitLab dashboard. The settings to configure for Mintlify are highlighted." />
    </Frame>

  </Step>
  <Step title="Set up the connection">
    In the [Mintlify dashboard](https://dashboard.mintlify.com/settings/<RainbowText>deployment</RainbowText>/git-settings):
    1. Enter your project ID and access token.
    2. Complete any other required configurations.
    3. Click **Save Changes**.
    <Frame>
      <img src="/images/gitlab/gitlab-config-light.png" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="block dark:hidden" />
      <img src="/images/gitlab/gitlab-config-dark.png" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="hidden dark:block" />
    </Frame>
  </Step>
</Steps>

## Create the webhook

Webhooks allow us to receive events when changes are made so that we can
automatically trigger deployments.

<Steps>
  <Step title="Add new webhook">
  1. In GitLab, navigate to **Settings** > **Webhooks**.
  2. Click **Add new webhook**.
    <Frame>
      <img src="/images/gitlab/gitlab-webhook.png" alt="Screenshot of the Webhooks page in the GitLab dashboard." />
    </Frame>
  </Step>
  <Step title="Set up URL and webhook">
    Name the webhook **Mintlify**.

    In the **URL** field, enter the endpoint `https://leaves.mintlify.com/gitlab-webhook`.
  </Step>
  <Step title="Get webtoken">
    In your Mintlify dashboard, click **Show Webtoken**. Copy the webtoken.
    <Frame>
      <img src="/images/gitlab/show-webtoken-light.png" alt="Screenshot of the GitLab connection in the Mintlify dashboard." className="block dark:hidden" />
      <img src="/images/gitlab/show-webtoken-dark.png" alt="Screenshot of the GitLab connection in the Mintlify dashboard." className="hidden dark:block" />
    </Frame>
  </Step>
  <Step title="Paste webtoken">
    In GitLab, paste the webtoken from your Mintlify dashboard in the **Secret token** field.
  </Step>
  <Step title="Select events">
    Select the following events to trigger the webhook:
    - **Push events** (All branches)
    - **Merge requests events**
  </Step>
  <Step title="Verify the webhook">
    You should see the following settings after configuring the webhook:
    
    - **Name**: Mintlify
    - **URL**: `https://leaves.mintlify.com/gitlab-webhook`
    - **Secret token**: The webtoken from your Mintlify dashboard
    - **Events**: **Push events** (All branches) and **Merge requests events**

    Add the webhook.

    <Frame>
      <img src="/images/gitlab/gitlab-project-webtoken.png" alt="The Webhook page in the GitLab dashboard. The settings to configure for Mintlify are highlighted." />
    </Frame>
  </Step>
  <Step title="Test the webhook">
    After you create the webhook, click the **Test** dropdown. Click **Push events** to send a sample payload. If the test returns `Hook executed successfully: HTTP 200`, your webhook is configured correctly.

    <Frame>
      <img src="/images/gitlab/gitlab-project-webtoken-test.png" alt="Screenshot of the GitLab Webhooks page. The 'Push events' menu item is highlighted in the 'Test' menu." />
    </Frame>

  </Step>
</Steps>