OrgMCP/ docs
Sign up
Documentation
Get started
Connectors
MCP integration
Reference
Enterprise
Misc

GitLab connector

Two flavours: GitLab OAuth (recommended) and a personal access token (including self-managed GitLab via an optional host). Both index the same repository tree into the knowledge corpus and power the live MCP tools (gitlab_list_projects, gitlab_list_issues, gitlab_list_merge_requests, gitlab_get_file, gitlab_diagnose).

Option A — OAuth (recommended)

  1. In the OrgMCP admin console, open Connectors → Add → GitLab, or from Personal connectors connect GitLab for your own account.
  2. Click Connect to GitLab. Approve the read scopes (read_api, read_repository, read_user).
  3. GitLab redirects to /api/oauth-tenant/gitlab/callback (workspace) or /api/oauth/gitlab/callback (personal). We persist the token blob (including refresh token + client id/secret so refresh works without a second config lookup) and bounce you back to the connectors UI.
  4. On the connector's Sources tab, pick the projects to index as knowledge sources.

Ops note: the GitLab OAuth Application must list both redirect URIs for each environment — e.g. https://staging.app.orgmcp.io/api/oauth/gitlab/callback and https://staging.app.orgmcp.io/api/oauth-tenant/gitlab/callback (and the production https://app.orgmcp.io/… pair).

Rotation: expired access tokens refresh automatically when a refresh_token is present. Reconnect if refresh fails.

Option B — Personal access token

  1. On GitLab: Preferences → Access Tokens (or your self-managed equivalent). Create a token with read_api and read_repository.
  2. In Connectors → Add → GitLab, optionally set Host to your self-managed base URL (e.g. https://gitlab.example.com) — leave blank for gitlab.com. Paste the glpat-… token.
  3. Click Test connection. A green result requires at least one visible project; zero projects fails with a clear message (use gitlab_diagnose / the diagnostics panel for host + project count).

What gets indexed

  • Text files matching the ingest extension allowlist on the crawl ref (default branch unless overridden) — markdown, reST, plain text, and common source languages.
  • Tip-SHA short-circuit: unchanged tip skips the re-walk; a 24h reconcile always re-walks.
  • Path allowlists / ignore lists on the knowledge source narrow the crawl; empty path filters that exclude everything surface an honest emptyReason.

What does not get indexed

  • Binary files — skipped during ingest.
  • Issues and merge-request bodies — available via live MCP tools, not the knowledge corpus.
  • Projects the credential cannot see (membership / token scope). Diagnose surfaces the visible count.

Honesty surface

  • gitlab_diagnose / admin Test — mode, host, visible project count, sample paths. Zero projects ⇒ test fails.
  • List tools paginate with pageToken / nextPageToken.
  • Partial syncs at the file cap write a warning; empty crawls write a precise emptyReason.

See also GitHub connector for the parallel Wave-1 honesty pattern, and Personal connectors for the per-user OAuth path.