Source Integrations # GitLab Connect a gitlab.com repository to an MCP server using either an OAuth application or a Personal Access Token. Three GitLab-specific quirks bite users: the glpat- token prefix that routes PATs to a different auth header, the internal visibility trap, and the gitlab.com-only base URL. ## When to pick GitLab Pick GitLab if your repository is hosted on gitlab.com. Self-hosted GitLab is on the roadmap but not supported here yet — the base URL is hard-pinned to https://gitlab.com/api/v4. See "Self-hosted GitLab" below for status. ## Option A — Connect with GitLab (OAuth) Click Connect with GitLab on the integration form, complete the consent on gitlab.com, and you land back on the integration's edit page with the connection established. ### OAuth scopes requested - `read_user` — used to identify the connecting account. - `read_repository` — required to list branches, walk the tree, and fetch files. **Do NOT request api or write\_repository:** Both grant write access the import pipeline does not need. The api scope grants full read AND write across the user's entire GitLab account; write\_repository is equally excessive. The Vectoralix import pipeline is strictly read-only. ### Access token lifetime GitLab OAuth access tokens live for two hours by default on gitlab.com. Refresh-token handling is not yet wired in the integration — same status as Bitbucket OAuth. For long-lived production use, prefer the PAT path until refresh handling lands. ## Option B — Personal Access Token GitLab PATs minted in the last few years start with a glpat- prefix. The integration detects the prefix and sends the credential as PRIVATE-TOKEN: {token} rather than Authorization: Bearer. Token Prefix HTTP header sent Personal Access Token `glpat-…` `PRIVATE-TOKEN: ` OAuth access token *no prefix* `Authorization: Bearer ` Minimum scopes for the PAT path: - `read_api` — required to hit /user and the /projects list. - `read_repository` — required to list branches, walk the tree, and fetch files. - `read_user` — required, or GET /user will 403 during validation. ### Legacy PATs without the glpat- prefix PATs minted before 2021 have no glpat- prefix and will be misrouted as OAuth bearers, causing a 401. There is no runtime fallback because that would let a corrupted OAuth token be retried as a PAT, doubly leaking it. Rotate the PAT on GitLab's side to mint a current-format token. ## Repository addressing Repository Name takes the namespace/project form, for example mygroup/myproj or group/sub/proj for nested groups. Paths with spaces or slashes are URL-encoded by the integration as one opaque segment, matching GitLab's API contract. ## API endpoints used Method Endpoint Purpose GET `/user` Authenticate token, capture identity GET `/projects?membership=true` List accessible projects (paginated via Link header) GET `/projects/{path}/repository/branches` List branches GET `/projects/{path}/repository/tree?recursive=true` List the entire branch tree, paginated by Link header GET `/projects/{path}/repository/files/{encoded_file_path}/raw` Fetch a single file body ## The internal visibility trap **Internal is not public:** GitLab projects have three visibility levels: public, internal, and private. The Vectoralix UI collapses these to two and labels anything that is not public as private. This is intentional — internal means "any authenticated gitlab.com user can see it", which is not public, but users often assume "internal" means "public inside the company". ## Caps to know about - Tree pagination is capped at 50 pages — roughly 5,000 entries at 100 per page. Beyond that, the integration logs a notice and returns the partial result. - Tree traversal has a 30-second wall-clock budget. On breach, partial results are returned with a notice. - Maximum blob size is 10 MB. Larger files are skipped with a per-file error and the import continues. - Submodules appear as commit rows in the GitLab tree and are skipped — they have no downloadable body. ## Rate limits gitlab.com enforces approximately 2,000 authenticated requests per minute per user. The signal is HTTP 429 with a Retry-After header. ## Self-hosted GitLab status Self-hosted GitLab is not supported in the current integration. Only repositories on gitlab.com can be connected — the base URL is hard-pinned to https://gitlab.com/api/v4. Support for self-hosted GitLab instances is on the roadmap.