IntegrationsGitLab

GitLab Integration

Connect a GitLab project as your documentation source repository, with support for self-hosted instances, auto-deploy on push, and token management.

Overview

Connect a GitLab project on gitlab.com or a self-hosted instance and use it as the single source of truth for your documentation. Documentation.AI syncs content from your GitLab repository and can auto-deploy when you push changes.

Use this integration to sync and publish documentation from a Git repository. If you want to connect repositories for the AI agent's GitHub App context, see the GitHub Integration.

Before you start

Make sure you have the required access in both Documentation.AI and GitLab before you connect your project.

  • An organization or workspace admin role in Documentation.AI
  • A GitLab project with at least Developer access, minimum role 30
  • A project or personal access token with the api scope
  • At least one documentation project created in your Documentation.AI workspace

Connect a GitLab project

Follow these steps in Git Settings to connect your repository and enable syncing.

Open Git Settings

In the Documentation.AI dashboard, go to Settings → Git Settings. Use the provider selector at the top of the page to switch from GitHub to GitLab.

Enter your project details

Enter your GitLab Project ID and your access token. You can use either the numeric project ID from your GitLab project's settings page or the namespaced path, such as group/project.

Connect a self-hosted instance

If your project is hosted on your own GitLab instance, enable the self-hosted option and enter the full instance URL, such as https://gitlab.internal.company.com. If you use gitlab.com, leave this option off.

Connect and verify

Click Connect. Documentation.AI validates the token and project, stores the connection, and attempts to register a webhook for auto-deploy.

If your token can access the project but cannot create webhooks, Git Settings shows a warning during setup. The repository still connects, but pushes will not trigger automatic deployments.

Token permissions

Your GitLab role determines whether Documentation.AI can only publish manually or also enable auto-deploy.

  • Developer, minimum role 30 — Connects the project and publishes documentation manually, but cannot register a webhook. Auto-deploy does not work at this permission level.
  • Maintainer, minimum role 40 — Connects the project, publishes documentation, and registers a webhook for auto-deploy. This is the recommended permission level.

GitLab removed non-expiring tokens in v16.0. Rotate tokens on a schedule and update the token in Documentation.AI before it expires to avoid interrupted syncs or failed deploys.

Auto-deploy on push

Pushes to your deployment branch can trigger a build automatically after the GitLab connection is in place. Documentation.AI does this by registering a webhook on the connected project.

If you connect with a Maintainer-level token, webhook registration happens during setup and future pushes deploy automatically. If webhook registration fails, Git Settings shows a warning and pushes do not auto-deploy.

You can still publish manually from the editor when the repository is connected but the webhook is unavailable.

Update an expired token

Replace expired or revoked tokens from Git Settings without reconnecting the project.

Open Git Settings

Go to Settings → Git Settings and select GitLab.

Update the token

Click Update Token and enter a new access token with the required scope.

Verify

The connection status updates immediately after the token is accepted. If the previous token had put the integration into an error state, Documentation.AI clears that error automatically.

When a token is expired, revoked, or otherwise rejected, the editor shows a blocking overlay with an inline Update Token button so you can fix the connection without leaving your work.

Disconnect GitLab

Disconnect the repository when you want to stop syncing or switch to a different provider.

Open Git Settings

Go to Settings → Git Settings and select GitLab.

Disconnect

Click Disconnect. Documentation.AI removes the webhook from your GitLab project and then removes the repository connection.

Disconnecting your Git provider stops all syncing and auto-deploy. Your published documentation stays live, but new changes do not deploy until you reconnect a provider.

Troubleshooting

Use these checks if the connection succeeds partially, auto-deploy does not work, or GitLab rejects your token.

Was this page helpful?