Self-hosted GitLab OAuth

Connect a self-hosted GitLab instance to Mintlify via OAuth so workflows can clone repositories, push commits, and open merge requests on your behalf.

Mintlify supports OAuth-based authorization for self-hosted GitLab instances, in addition to gitlab.com. OAuth lets the Mintlify agent act as a GitLab user during workflow runs: cloning repositories, pushing commits, opening merge requests, and registering project webhooks.

You must configure OAuth authorization for self-hosted GitLab instances to support workflows.

Unlike gitlab.com, where Mintlify ships a single OAuth application that every customer authorizes against, each self-hosted instance must register its own OAuth application. Create the application on your GitLab instance, share its credentials with Mintlify, and then go through an OAuth authorization to connect a user.

This guide is only for the OAuth integration that powers workflows. You must configure the deployment-side connection (used for content sync and previews) separately with a deploy token, see the GitLab guide. The OAuth integration depends on the deployment-side connection.

Prerequisites

• Admin access to your self-hosted GitLab instance.
• Your GitLab instance must be reachable from https://dashboard.mintlify.com. Instances behind a VPN or behind a firewall that blocks public ingress do not work.
• A Mintlify organization that has the self-hosted GitLab feature enabled. Contact support if you don’t see the Self-hosted GitLab section in your Git settings dashboard page.

Set up the connection

1. Register an OAuth application on your GitLab instance

   In your self-hosted GitLab, sign in as an admin and navigate to Admin Area > Applications > Add new application.

   Configure the application with these values:

   • Name: Mintlify
   • Redirect URI: https://dashboard.mintlify.com/api/gitlab-oauth/callback
   • Trusted: leave unchecked. Trusting the application skips the consent screen for every user; leaving it unchecked surfaces a normal authorization prompt the first time each user connects.
   • Confidential: checked. Mintlify is a server-side client and keeps the secret confidential.
   • Scopes: select api, read_repository, and write_repository. The agent uses these to read project metadata, clone repositories, and push commits.

   Click Save application.

   Editing an OAuth application on GitLab can rotate the client secret silently. If you make changes later, click Renew secret and update the new value in Mintlify.

2. Copy the application credentials

   After saving, GitLab displays the application’s Application ID and Secret. Keep this page open—the secret is only shown once.

3. Register the instance in Mintlify

   In your Mintlify dashboard, open Settings > Git settings and find the Self-hosted GitLab section under GitLab OAuth.

   Click Connect Self-Hosted GitLab and enter:

   • GitLab instance URL: the public URL of your GitLab instance, for example https://gitlab.your-company.com. Mintlify reaches your instance through this URL when exchanging tokens and calling the GitLab API.
   • OAuth application client ID: the Application ID from the previous step.
   • OAuth application client secret: the Secret from the previous step.

   Click Save instance. Mintlify encrypts the secret at rest and never returns it to the browser after saving.

4. Authorize

   Click Authorize self-hosted GitLab. You’ll be redirected to your GitLab instance, prompted to sign in if needed, and shown a consent screen listing the requested scopes.

   After you click Authorize on GitLab, you’ll be redirected back to Mintlify and the new connection appears in the installations list, badged with your instance hostname.

5. Choose projects

   Expand the connection in the dashboard. Mintlify lists every group your authorizing user has Maintainer or higher access to, plus a Personal projects entry for projects in the user’s personal namespace.

   Check the box next to each project that should participate in workflows. Mintlify registers a webhook on the project, generates a secret token, and stores it encrypted. From then on, Mintlify receives push and merge-request events from your instance for that project.

   The connecting user must have Maintainer role on a project for Mintlify to mint short-lived project access tokens during workflow runs. Without Maintainer, the agent can read but cannot push commits or open merge requests.

Rotate credentials

If you need to change the registered application’s client secret—for example after renewing it on GitLab—remove the saved instance in Mintlify and add it again with the new values. You must revoke active OAuth connections first; otherwise Mintlify blocks the removal.

1. Revoke each connection

   Click Revoke on every installation listed under the self-hosted instance. This removes the webhook on every connected project and revokes the OAuth token on GitLab.

2. Remove the instance

   In the Self-hosted GitLab card, click Remove instance.

3. Re-add with new credentials

   Follow the Set up the connection steps described earlier with the new client secret.

Troubleshooting

invalid_client after authorizing

GitLab rejected the token-exchange step because the client secret Mintlify sent doesn’t match what’s registered on the application. The most common cause is that a secret rotated on GitLab—by an explicit Renew secret, or silently when someone edited the application—and the value in Mintlify is stale.

Fix: rotate credentials following the Rotate credentials steps with the current secret.

Webhook registration failed: Invalid url given

GitLab refused to register the webhook because the URL Mintlify sent (https://dashboard.mintlify.com/gitlab-oauth-webhook) was rejected by GitLab’s outbound-request allowlist. Self-hosted instances reject “local” URLs unless the admin explicitly allows them.

Fix: in your GitLab admin area, go to Settings > Network > Outbound requests and enable Allow requests to the local network from webhooks and integrations. If your network policy blocks dashboard.mintlify.com, contact your network admin to allow outbound HTTPS to that host.

No consent screen on authorize

If you don’t see GitLab’s consent dialog when authorizing, either:

• The application is marked Trusted on GitLab. Trusted applications skip consent for all users. Uncheck Trusted in the application settings if you want users to see and confirm scopes.
• Your GitLab user has previously authorized the application with the same scopes. GitLab remembers prior grants and skips consent on subsequent authorizes. Revoke the application authorization in User settings > Applications > Authorized applications to see consent again.