Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify-mintlify-docs-gitlab-self-hosted-oauth-1778199001.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through connecting a self-hosted GitLab instance to Mintlify. You register an OAuth application on your GitLab instance, then provide its client ID and secret in your Mintlify dashboard so workflows can authorize against your instance. If you use GitLab.com, see the GitLab page for setup instructions.

​
Prerequisites

  • Admin or maintainer access to your GitLab instance to register an OAuth application
  • A publicly accessible URL for your GitLab instance so Mintlify can reach it
  • Access to your Mintlify dashboard with the Self-hosted GitLab OAuth feature enabled for your organization

​
Step 1: Register the OAuth application on your GitLab instance

Register a new OAuth application on your GitLab instance. You can do this at the instance, group, or user level depending on how you want to scope access.
1

Navigate to OAuth applications

On your GitLab instance, go to Admin Area > Applications to register an instance-wide application, or User Settings > Applications to register one under your user account.
2

Configure the application

Set the following fields:
  • Name: Mintlify
  • Redirect URI: https://leaves.mintlify.com/gitlab-oauth-webhook
  • Confidential: Enabled
  • Scopes: api, read_repository, write_repository
The api scope is required so Mintlify can read project metadata and create webhooks. The read_repository and write_repository scopes allow Mintlify to clone your documentation and push preview deployments.
3

Save and record credentials

Save the application. GitLab displays the Application ID (client ID) and Secret (client secret). Record both before leaving the page; the secret is only shown once.

​
Step 2: Connect your instance in the Mintlify dashboard

1

Open the GitLab OAuth settings

In your Mintlify dashboard, go to Settings > Git settings > GitLab OAuth, then locate the Self-hosted GitLab section.
2

Enter your instance details

Click Connect Self-Hosted GitLab and fill in the following fields:
  • GitLab instance URL: The base URL of your instance, for example https://gitlab.your-company.com.
  • OAuth application client ID: The Application ID from Step 1.
  • OAuth application client secret: The Secret from Step 1.
Click Save instance. Your client secret is encrypted at rest and is never returned by the API after saving.
3

Authorize the connection

Click Authorize self-hosted GitLab. You are redirected to your instance to approve the OAuth application, then sent back to the dashboard.
4

Connect projects

Expand a group in the installations list and select the projects you want to connect. Mintlify enables webhooks on each selected project so deployments trigger automatically when you push changes.

​
Rotate or remove credentials

To rotate your OAuth credentials, remove the existing instance from the Self-hosted GitLab section and add it again with the new client ID and secret. Removing an instance also revokes any active installations connected through it.

​
Troubleshooting

Self-hosted GitLab OAuth is gated behind an organization feature flag. Contact your customer success representative or support@mintlify.com to enable it for your organization.
The redirect URI registered on your OAuth application must exactly match https://leaves.mintlify.com/gitlab-oauth-webhook. Update your application on GitLab and try again.
Your instance must be reachable from the public internet. Verify your firewall allows inbound HTTPS connections from Mintlify and that your instance has a valid SSL certificate.
The user who authorized the OAuth application must have at least the Maintainer role on each connected project. Reauthorize with a user that has the required role, or upgrade the role on the affected projects.