mintlify__docs/deploy/gitlab.mdx

---
title: "GitLab"
description: "Connect your GitLab repository to Mintlify for automated documentation deployments, merge request previews, and continuous synchronization."
keywords: ["GitLab integration", "access tokens", "merge request previews", "self-hosted", "instance"]
---

Mintlify uses 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 you make changes, which enables preview deployments for merge requests.

## Set up the connection

<Tip>
  If you selected GitLab during onboarding, the setup wizard guides you through these steps automatically. The instructions below are for connecting GitLab after onboarding or when changing your Git provider.
</Tip>

<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/deployment/git-settings):
    1. Enter your project ID and access token.
    2. If you have a monorepo and your documentation is not at the root of your repository, enable the **Set up as monorepo** toggle and enter the relative path to your docs directory.
    3. If you use a self-hosted GitLab instance, enable the **Set up as self-hosted** toggle and enter your GitLab instance's host URL (for example, `https://gitlab.your-domain.com`). Your instance must be publicly accessible for Mintlify to reach it.
    4. Select the branch to deploy your documentation from.
    5. 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 notify Mintlify when you push changes so that deployments trigger
automatically.

<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`, you configured the webhook 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>