mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
4c31f3683c
* ai/ keywords * api/ keywords * components/ keywords * create/ keywords * customize/ keywords * api-playground/ keywords * dashboard/ keywords * deploy/ keywords * guides/ keywords * insights/ keywords * integrations/ keywords * optimize/ keywords * organize/ keywords * root/ keywords * rm temp files
96 lines
4.1 KiB
Plaintext
96 lines
4.1 KiB
Plaintext
---
|
|
title: "GitLab"
|
|
description: "Connect to a GitLab repository for automated deployments and preview builds."
|
|
keywords: ["GitLab integration", "access tokens", "merge request previews"]
|
|
---
|
|
|
|
We use 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 changes are made, enabling preview deployments for merge requests.
|
|
|
|
## Set up the connection
|
|
|
|
<Note>
|
|
**HTTPS cloning required**: Your GitLab project must have HTTPS cloning enabled for Mintlify to access your repository. You can verify this in GitLab by going to your project's **Settings** > **General** > **Visibility and access controls** section.
|
|
</Note>
|
|
|
|
<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. Complete any other required configurations.
|
|
3. Click **Save Changes**.
|
|
<Frame>
|
|
<img src="/images/gitlab/gitlab-config.png" alt="The Git Settings page in the Mintlify dashboard. The GitLab configuration settings are highlighted." />
|
|
</Frame>
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Create the webhook
|
|
|
|
Webhooks allow us to receive events when changes are made so that we can
|
|
automatically trigger deployments.
|
|
|
|
<Steps>
|
|
<Step title="Navigate to Settings > Webhooks and 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">
|
|
In the "URL" field, enter the endpoint `https://leaves.mintlify.com/gitlab-webhook` and name the webhook "Mintlify".
|
|
|
|
</Step>
|
|
<Step title="Paste token">
|
|
Paste the Webhook token generated after setting up the connection.
|
|
<Frame>
|
|
<img src="/images/gitlab/gitlab-show-webtoken.png" alt="Screenshot of the GitLab connection in the Mintlify dashboard. The Show Webtoken button is highlighted." />
|
|
</Frame>
|
|
</Step>
|
|
<Step title="Select events">
|
|
Select these events to trigger the webhook:
|
|
- **Push events** (All branches)
|
|
- **Merge requests events**
|
|
|
|
When you're done it should look like this:
|
|
<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 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.
|
|
<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>
|