GitLab

Connect to a GitLab repository for automated deployments and preview builds.

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

1. Find your project ID

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

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

   
3. Set up the connection

   In the Mintlify dashboard:

   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.

   

Create the webhook

Webhooks allow us to receive events when changes are made so that we can automatically trigger deployments.

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, your webhook is configured correctly.