> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect your GitLab repository to Mintlify for automated documentation deployments, merge request previews, and continuous synchronization.

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

When you open [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) for the first time, a setup wizard guides you through connecting your GitLab repository.

<Steps>
  <Step title="Select GitLab as your provider">
    On the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page, click **Connect to GitLab** and then click **Continue**.
  </Step>

  <Step title="Download your content">
    <Tip>
      If you already have a GitLab repository with your documentation, you can skip the download and click **Continue setup** directly.
    </Tip>

    If your documentation is hosted by Mintlify, download it as a zip file.

    * Create a new repository in GitLab.
    * Extract the zip contents.
    * Push the contents to your repository.

    Click **Continue setup** to proceed.
  </Step>

  <Step title="Find your project ID">
    In your GitLab project, navigate to **Settings** > **General** and locate your **Project ID**.

    <Frame>
      <img src="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gitlab/gitlab-project-id.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=4aae3ff6adbb509b607a63a4998992d0" alt="The General Settings page in the GitLab dashboard. The Project ID is highlighted." width="950" height="775" data-path="images/gitlab/gitlab-project-id.png" />
    </Frame>
  </Step>

  <Step title="Generate an access token">
    Navigate to **Settings** > **Access Tokens** and click **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="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gitlab/gitlab-project-access-token.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=59ef23c54d88cdd723632086bced658b" alt="The Access tokens page in the GitLab dashboard. The settings to configure for Mintlify are highlighted." width="1166" height="904" data-path="images/gitlab/gitlab-project-access-token.png" />
    </Frame>
  </Step>

  <Step title="Connect your repository">
    Back in the setup wizard, fill in the following fields:

    * **GitLab instance URL**: Leave blank for `gitlab.com`, or enter your self-hosted instance URL (for example, `https://gitlab.your-domain.com`). Your instance must be publicly accessible for Mintlify to reach it.
    * **Project ID**: The project ID from your GitLab project settings.
    * **GitLab deployment token**: The access token you generated.
    * **Branch**: Select the branch to deploy your documentation from.

    Click **Connect**.

    <Frame>
      <img src="https://mintcdn.com/mintlify/s5oOjnzImG1zHVbH/images/gitlab/gitlab-config-light.png?fit=max&auto=format&n=s5oOjnzImG1zHVbH&q=85&s=99d816a0c091b4e3bc2e67bc2618e8ba" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="block dark:hidden" width="1052" height="1136" data-path="images/gitlab/gitlab-config-light.png" />

      <img src="https://mintcdn.com/mintlify/s5oOjnzImG1zHVbH/images/gitlab/gitlab-config-dark.png?fit=max&auto=format&n=s5oOjnzImG1zHVbH&q=85&s=9cb4024359475d16b08576dffdbc036a" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="hidden dark:block" width="1052" height="1138" data-path="images/gitlab/gitlab-config-dark.png" />
    </Frame>
  </Step>
</Steps>

## Update an existing connection

To modify your GitLab connection settings after the initial setup, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and update your project ID, access token, branch, or instance URL directly.

## Revalidate Git settings

If your deployment shows unexpected behavior, such as missing branch options or stale configuration, you can force Mintlify to refresh your Git source.

<Steps>
  <Step title="Navigate to Git Settings">
    Go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard.
  </Step>

  <Step title="Revalidate your settings">
    Click the green **Active** badge in the corner of the GitLab settings box to revalidate your Git source.
  </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="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gitlab/gitlab-webhook.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=760e8faa2437ecf8ff2739c4dfa0bdc4" alt="Screenshot of the Webhooks page in the GitLab dashboard." width="3014" height="1704" data-path="images/gitlab/gitlab-webhook.png" />
    </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="https://mintcdn.com/mintlify/iZZGgKQ6swbDUuUa/images/gitlab/show-webtoken-light.png?fit=max&auto=format&n=iZZGgKQ6swbDUuUa&q=85&s=50d2acef9a5f88b607128f7c5292743c" alt="Screenshot of the GitLab connection in the Mintlify dashboard." className="block dark:hidden" width="1082" height="980" data-path="images/gitlab/show-webtoken-light.png" />

      <img src="https://mintcdn.com/mintlify/iZZGgKQ6swbDUuUa/images/gitlab/show-webtoken-dark.png?fit=max&auto=format&n=iZZGgKQ6swbDUuUa&q=85&s=9fa9732011ac61c1250ebae004de87be" alt="Screenshot of the GitLab connection in the Mintlify dashboard." className="hidden dark:block" width="1082" height="980" data-path="images/gitlab/show-webtoken-dark.png" />
    </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="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gitlab/gitlab-project-webtoken.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=00c0ce70ce9e8dbc2712f71aaeef3362" alt="The Webhook page in the GitLab dashboard. The settings to configure for Mintlify are highlighted." width="1161" height="1740" data-path="images/gitlab/gitlab-project-webtoken.png" />
    </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="https://mintcdn.com/mintlify/GiucHIlvP3i5L17o/images/gitlab/gitlab-project-webtoken-test.png?fit=max&auto=format&n=GiucHIlvP3i5L17o&q=85&s=3ad52f7ac39124a4c03944256d0b79d3" alt="Screenshot of the GitLab Webhooks page. The 'Push events' menu item is highlighted in the 'Test' menu." width="1161" height="724" data-path="images/gitlab/gitlab-project-webtoken-test.png" />
    </Frame>
  </Step>
</Steps>


## Related topics

- [Workflows overview](/docs/workflows/index.md)
- [Playground](/docs/api-playground/overview.md)
- [GitHub](/docs/deploy/github.md)