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 for the first time, a setup wizard guides you through connecting your GitLab repository.

1. Select GitLab as your provider

   On the Git Settings page, click Connect to GitLab and then click Continue.

2. Download your content

   If you already have a GitLab repository with your documentation, you can skip the download and click Continue setup directly.

   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.

3. Find your project ID

   In your GitLab project, navigate to Settings > General and locate your Project ID.

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

   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.

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

   

Update an existing connection

To modify your GitLab connection settings after the initial setup, go to 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.

1. Navigate to Git Settings

   Go to Git Settings in your dashboard.

2. Revalidate your settings

   Click the green Active badge in the corner of the GitLab settings box to revalidate your Git source.

Create the webhook

Webhooks notify Mintlify when you push changes so that deployments trigger automatically.

1. Add new webhook

   1. In GitLab, navigate to Settings > Webhooks.
   2. Click Add new webhook.

   
2. Set up URL and webhook

   Name the webhook Mintlify.

   In the URL field, enter the endpoint https://leaves.mintlify.com/gitlab-webhook.

3. Get webtoken

   In your Mintlify dashboard, click Show Webtoken. Copy the webtoken.

   
4. Paste webtoken

   In GitLab, paste the webtoken from your Mintlify dashboard in the Secret token field.

5. Select events

   Select the following events to trigger the webhook:

   • Push events (All branches)
   • Merge requests events
6. 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.

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

   

Self-hosted GitLab OAuth

If you run GitLab on your own infrastructure, you can connect your self-hosted instance to Mintlify through OAuth. This connection is used by workflows and the agent to read repositories, listen for push and merge request events, and open merge requests.

Self-hosted GitLab OAuth is currently available on Enterprise plans. Contact your Mintlify representative if you don’t see the option in your dashboard.

Connecting a self-hosted instance is a two-step process:

1. Register an OAuth application on your GitLab instance.
2. Save the application credentials in your Mintlify dashboard, then authorize.

Register an OAuth application on your GitLab instance

You can register the OAuth application as either an instance-wide application (admin only) or a group-owned application. A group-owned application is usually sufficient and does not require admin access.

1. Open the application settings

   Sign in to your GitLab instance as an admin or group owner.

   • Instance-wide: Go to Admin Area > Applications and click Add new application.
   • Group-owned: Open your group, then go to Settings > Applications and click Add new application.
2. Configure the application

   Use these values:

   • Name: Mintlify
   • Redirect URI: https://leaves.mintlify.com/gitlab-oauth/callback
   • Confidential: Enabled
   • Scopes: api and read_api

   Save the application.

3. Copy the credentials

   GitLab displays the Application ID and Secret. Copy both values now—the secret is only shown once.

Save credentials in your Mintlify dashboard

1. Open Git Settings

   Go to Git Settings and find the Self-hosted GitLab card under the GitLab OAuth section.

2. Enter your instance details

   Click Connect Self-Hosted GitLab and fill in:

   • GitLab instance URL: The base URL of your instance (for example, https://gitlab.your-company.com). Must start with https:// or http://.
   • OAuth application client ID: The Application ID from the previous step.
   • OAuth application client secret: The Secret from the previous step. Encrypted at rest and never returned by the API after saving.

   Click Save instance.

3. Authorize the connection

   Click Authorize self-hosted GitLab. You’ll be redirected to your GitLab instance to approve the OAuth scopes, then returned to the dashboard.

   After authorization, expand the new connection to browse groups and enable individual projects.

Manage the connection

• Add multiple users: Each member of your organization can authorize their own GitLab account against the same self-hosted instance. Click Add another GitLab connection to add more users.
• Rotate credentials: To rotate the client secret, remove the saved instance and add it again with the new value. You must revoke any active OAuth connections first.
• Remove the instance: Click Remove instance on the Self-hosted GitLab card. Existing webhooks for connected projects are removed.

Requirements

• The GitLab instance must be reachable from leaves.mintlify.com. Mintlify cannot connect to instances behind a VPN or IP allowlist that blocks our egress.
• You need at least the Maintainer role on each GitLab project you want to connect, so that Mintlify can install webhooks.
• Only one self-hosted instance can be configured per Mintlify organization.