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", "OAuth", "access tokens", "merge request previews", "self-hosted", "instance"]
---

Mintlify integrates with GitLab to pull your documentation source and automatically deploy when you push changes. You can connect using either OAuth or a manual access token.

- **OAuth** (recommended): Authorize Mintlify through GitLab and select which projects to connect. Mintlify manages tokens and webhooks automatically.
- **Access token**: Manually generate an access token and configure a webhook in GitLab. Use this method for self-hosted GitLab instances.

## Connect with OAuth

OAuth is the fastest way to connect your GitLab projects. Mintlify handles token management and webhook registration so you don't need to configure anything in GitLab.

<Steps>
  <Step title="Start the OAuth flow">
    In the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings), select **GitLab** as your Git provider and click **Connect with GitLab**. This redirects you to GitLab to authorize the Mintlify application.
  </Step>
  <Step title="Authorize Mintlify">
    On the GitLab authorization page, review the requested permissions and click **Authorize**. You are redirected back to the Mintlify dashboard.
  </Step>
  <Step title="Select a project">
    After authorization, browse your GitLab groups and select the project that contains your documentation. Mintlify automatically registers a webhook on the project to listen for push and merge request events.
  </Step>
  <Step title="Configure deployment settings">
    1. 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.
    2. Select the branch to deploy your documentation from.
    3. Click **Save Changes**.
  </Step>
</Steps>

<Note>
  You can connect multiple projects under the same GitLab authorization. To disconnect a project, go to **Git Settings** in your dashboard and remove it. Mintlify automatically cleans up the associated webhook.
</Note>

## Connect with an access token

Use this method if you need to connect a self-hosted GitLab instance or if your organization restricts OAuth applications.

### Set up the connection

<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. If you connected with OAuth, Mintlify creates the webhook for you and you can skip this section.

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