# GitLab (/deploy/gitlab)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1682 · updated: 2026-07-30 -->
Related: [Authentication setup](/deploy/authentication-setup.md), [CI checks](/deploy/ci.md), [Custom developer portals](/deploy/custom-portal.md), [Deployments](/deploy/deployments.md), [Offline export](/deploy/export.md), [GitHub Enterprise Server](/deploy/ghes.md)

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 [#set-up-the-connection]

When you open [Git Settings](https://app.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://app.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="/_assets/bb826ce16241f19d1ddc499f4b5fc82278e2567a3a38200e43e60f87899b2187" 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 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="/_assets/f6d06d9e88e7fab6ae076e532d8856ced528e236d2537adf9fbd8bf2cc056477" alt="The Access tokens page in the GitLab dashboard. The settings to configure for Mintlify are highlighted." />
    </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="/_assets/e692151369f14271f818eab32938733c6dacb4d1294956400454d0f9465cf537" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="block dark:hidden" />

      <img src="/_assets/c289e2dbc4fb9b0f76602dd21ea9533ae4f8dffcbed460b26b86f28b8cccb02c" alt="The GitLab configuration panel in the Git Settings page of the Mintlify dashboard." className="hidden dark:block" />
    </Frame>
  </Step>
</Steps>

## Update an existing connection [#update-an-existing-connection]

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

## Revalidate Git settings [#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://app.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 [#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="/_assets/0e4ee3d9ee09b3a73c8c65d831bbdd945cf3b468f6948c5d1c8f2d5060c8f0ae" 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="/_assets/abf6566843c168dbd23aed587f44ab8fcd9f0da83bb56888073fadae3de95463" alt="Screenshot of the GitLab connection in the Mintlify dashboard." className="block dark:hidden" />

      <img src="/_assets/8ee3868d172d45ee30cef080d04431979c6b5d660f552915022cb03d0546af8a" 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="/_assets/492254d1ca23ea8f27591b7ee98a8a3ef3104f844029cecc6f1e992b9b75a30f" 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="/_assets/748a9164b8483a9bc811a0173638a0e62269da2fe1b72419fe519a5d306b02a6" alt="Screenshot of the GitLab Webhooks page. The 'Push events' menu item is highlighted in the 'Test' menu." />
    </Frame>
  </Step>
</Steps>