Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 28 additions & 10 deletions deploy/gitlab.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,21 @@ Mintlify uses access tokens and webhooks to authenticate and sync changes betwee

## Set up the connection

When you open [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) for the first time, a setup wizard guides you through connecting your GitLab repository.

<Steps>
<Step title="Select GitLab as your provider">
In the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page, select **Connect to GitLab** and click **Continue**.
</Step>
<Step title="Download your content">
If your documentation is hosted by Mintlify, download it as a zip file. Create a new repository in GitLab, extract the zip contents, and push them to your repository.

Click **Continue setup** to proceed.

<Note>
If you already have a GitLab repository with your documentation, you can skip the download and click **Continue setup** directly.
</Note>
</Step>
<Step title="Find your project ID">
In your GitLab project, navigate to **Settings** > **General** and locate your **Project ID**.
<Frame>
Expand All @@ -20,12 +34,12 @@ Mintlify uses access tokens and webhooks to authenticate and sync changes betwee
</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>
Expand All @@ -35,22 +49,26 @@ Mintlify uses access tokens and webhooks to authenticate and sync changes betwee
<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**.
<Step title="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**.
<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>

### Update an existing connection

To modify your GitLab connection settings after the initial setup, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and update your project ID, access token, branch, or instance URL directly.

## Create the webhook

Webhooks notify Mintlify when you push changes so that deployments trigger
Expand Down
Loading