We use a combination of Access tokens and Webhooks to authenticate and sync changes between GitLab and Mintlify.
  • We use Access tokens to pull information from GitLab.
  • We use Webhooks so GitLab can notify Mintlify when changes are made.
    • This allows Mintlify to create preview deployments when a MR is created.

​
Set up the connection

1

Find your project ID

Within your GitLab project, navigate to Settings > General and find the Project ID.
2

Generate an access token

a. Navigate to Settings > Access Tokens.b. Select Add new token.
  1. Name the token “Mintlify”.
  2. If you have a private repo, you must set the role as Maintainer.
  3. Choose api and read_api for the scopes.
c. Finally click Create project access token and copy the token.
3

Set up the connection

Within the Mintlify dashboard, add the project ID and access token from the previous steps alongside the other configurations. Click “Save Changes” when you’re done.

​
Create the webhook

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

Navigate to Settings > Webhooks and click 'Add new Webhook'

2

Set up URL and webhook

In the “URL” field, enter the endpoint https://leaves.mintlify.com/gitlab-webhook and name the webhook “Mintlify”.
3

Paste token

Paste the Webhook token generated after setting up the connection.
4

Select events

Select the events you want to trigger the webhook:
  • Push events (All branches)
  • Merge requests events
When you’re done it should look like this:
5

Test the Webhook

After creating the Webhook, click the “Test” dropdown and select “Push events” to send a sample payload to ensure it’s configured correctly. It’ll say “Hook executed successfully: HTTP 200” if configured correctly.This will help you verify that everything is working correctly and that your documentation will sync properly with your GitLab repository.
Reach out to the Mintlify team if you need help. Contact us here.