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: <token> |
| OAuth access token | no prefix | Authorization: Bearer <token> |
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.