Connect one GitLab project per source. Choose an Administrator token to refresh permissions from GitLab, or a Non-admin token with two CSV files to manage access in Studio. Teammates do not connect individual GitLab accounts.
Organization admins set up sources in Settings → Sources. The same token paths are available when adding a GitLab connector to a regular knowledge base.
Choose a token path
| Administrator token | Non-admin token | |
|---|---|---|
| GitLab identity | Active instance administrator | Dedicated identity that can read the selected project's content; an Auditor identity is supported |
| PAT scopes | read_api; also admin_mode if Admin Mode is enabled | read_api; no admin_mode required |
| Permission source | GitLab directory, memberships, and source policy | Uploaded user mapping and project permissions |
| Membership changes | Refreshed from GitLab during background sync | An administrator must replace the CSV files |
| Confidential issues and their comments | Included only for users whose supported GitLab permissions allow access | Excluded |
Use a self-managed GitLab instance reachable by Studio over HTTPS. The administrator path requires GitLab 17.4 or later and access to administrator directory and settings APIs. A project Maintainer or group Owner is not an instance administrator.
The CSV path checks the token's identity and project access. It does not require administrator directory access or a custom admin role.
CSV files define access in Studio. Each mapped user listed for the selected project can read all of that source's indexed, non-confidential content. Studio does not infer that user's GitLab role or feature restrictions in this path. Include only users who should have that access, and replace the files whenever memberships or email mappings change.
Add a project
Create a personal access token
Sign in to GitLab as the identity you chose. Open Avatar → Edit profile → Access → Personal access tokens, then create a traditional scoped PAT. Navigation labels vary by GitLab version; see GitLab's token creation instructions.
Give the token a recognizable name, set an expiration date allowed by your instance, and select the scopes in the table above. Copy the value when GitLab displays it. Studio uses read-only GitLab API requests and scheduled sync; no webhook or write scope is needed.
For the non-admin path, give the identity read access to every content type you select. An Auditor identity can provide instance-wide read access on a licensed instance. A project-scoped service identity can be used when its project permissions are sufficient. See GitLab's Auditor permissions and token scopes.
Open GitLab setup
Open Settings → Sources → Add source, then select GitLab. If GitLab is already listed, open it and select Add project. In Add GitLab project, choose Administrator token or Non-admin token.
Fill in the shared fields. Switching tabs preserves the token, host, project, content choice, and other options.
| Field | What to enter |
|---|---|
| Personal Access Token | The PAT created above. |
| Host | Your self-managed domain, such as gitlab.example.com. |
| Project | The full group/project path or numeric project ID. Each connection crawls one project. |
| Content | Wiki & Issues by default. Select Code, Wiki, Issues & Merge Requests for all supported types. |
More options contains repository branch, path, and file-extension filters; issue state, label, and milestone filters; Max Items; and Metadata tags. Leave Max Items blank to index all matching items. Regular KB connectors also expose their sync schedule.
Upload permissions for a non-admin token
The Non-admin token tab requires both files. Use Download template beside each field title, replace its example rows, then drop the file into the upload field or click to browse. Files remain in the form until you save; validation errors appear beside the affected upload.
User mapping maps numeric GitLab user IDs to the verified email addresses those people use in Studio:
user_id,email
123,alice@example.com
456,bob@example.comProject permissions lists one project and user ID per grant:
project_path,user_id
engineering/platform,123
engineering/platform,456Use the full namespace path in project_path, even if you entered a numeric ID in the Project field. Use GitLab user IDs, not usernames. Include inherited group members when they should have access. Administrators can obtain IDs from GitLab's members API.
Both files follow these rules:
- At least one data row and exactly two columns, in the order shown. Headerless files and the exact template headers are accepted.
- UTF-8 CSV, at most 4 MiB and 100,000 data rows per file. The total request must also fit Studio's 10 MiB request limit.
- Identical rows are deduplicated. Conflicting user-ID/email mappings and malformed rows are rejected.
- A project-permission row whose user has no email mapping grants no access.
- Rows for other projects do not grant access to this source or expand its crawl.
Administrator-token setup does not require CSV uploads.
Connect and verify
Select Connect & Sync. Studio validates the token and configuration, saves the encrypted token and permissions, and starts indexing.
Open the source's Documents view to inspect the documents you can read, or Sync history to inspect sync outcomes. Have a listed teammate search for a known document, and verify that an unlisted teammate cannot find it.
For an organization, invite teammates through Settings → Members → Invite. They accept the invitation, sign in with a verified email, and search from Home. They do not need to press Connect for GitLab.
Teammates must belong to the owning Studio organization or workspace. The administrator path matches their confirmed primary GitLab email; the CSV path matches the uploaded email. Membership alone does not grant access to source documents.
What is indexed
The connector supports text repository files, wiki pages, issues, merge requests, and their non-internal comments. It does not index internal comments, binaries, or epics.
With CSV permissions, confidential issues and their comments are always excluded. Studio checks confidentiality during listing and again when fetching an issue. If a previously indexed issue becomes confidential, the next sync removes it from the index. An intentional confidential-issue exclusion does not create a failed sync.
Content and upstream confidentiality changes follow the source's sync schedule. CSV membership changes follow the replacement behavior below.
Update permissions or rotate the token
Open Settings → Sources → GitLab, select the project, and open Settings. Regular KBs expose the same fields in their connector settings.
To update membership, click either filename or drop its replacement into the same field, then Save. You can replace one file while retaining the other. Studio validates the resulting pair before committing anything. Invalid uploads preserve the saved configuration and grants. Settings displays filenames, row counts, and save status; it does not return saved CSV contents or the PAT.
A membership-only replacement takes effect on the next document or search read, without waiting for a crawl or re-embedding documents. Removed users lose access, and newly listed users gain access to existing indexed content. If another admin saved first, reload Settings and apply your changes to the latest revision.
To rotate the PAT, enter the replacement in Personal Access Token and save. Leave it blank to keep the saved token.
You can also switch token tabs or change the project. CSV mode requires both files; switching to the administrator path requires an administrator token. These changes temporarily block document access while Studio clears the old permissions and resyncs. If interrupted, keep the source active and resume syncing before expecting results.
Manage the connection
Open a project to use these administrator actions:
| Action | Effect |
|---|---|
| Sync now | Start a sync outside the schedule. An existing sync or a recent successful sync prevents another request. |
| Pause syncing / Resume syncing | Stop or resume scheduled updates. Pausing does not remove indexed content. |
| Settings | Change the token, project, filters, or CSV permissions. |
| Remove connection | Confirm removal of the connection and its indexed documents. Documents cannot be retained without the connection that maintains their permissions. |
Each sync checks the selected content. CSV grants change only when you replace the files.
Troubleshooting
| Problem | Next step |
|---|---|
| Administrator token required | Use an instance administrator PAT, or select Non-admin token and provide both CSV files. |
| Project not found or unreadable | Check Host, Project, token expiration, and the identity's access to the selected project and content types. |
| CSV validation error | Correct the reported row, column order, user ID, email, quoting, or conflicting mapping, then upload again. The saved files remain in effect. |
| Upload or request too large | Keep each file within 4 MiB and 100,000 rows, and the encoded request within 10 MiB. Remove unrelated project rows if needed. |
| A listed teammate sees no results | Check their verified Studio email, current organization/workspace membership, user mapping, and exact project path. Then check whether indexing has completed. |
| A removed teammate still sees results | Save the replacement file and run a new search. Check for another source or KB that independently grants access to the same content. |
| Confidential issue is missing | This is expected with CSV permissions. The administrator path can include it when the supported source permissions allow access. |
| Permissions changed while saving | Reload Settings and save against the latest files; a stale save cannot restore removed grants. |
| Token expired | Enter a new PAT in the source's Settings and save. PATs do not refresh automatically. |
| Source permissions cannot be mirrored | On the administrator path, review the reported GitLab policy. Unsupported external authorization, IP restrictions, download bans, or session-specific requirements remain unavailable. |
Custom GitLab roles can grant more access than the administrator path's conservative role mapping recognizes. CSV permissions are an explicit administrator-managed grant set, not automatic mirroring of those roles.
Self-hosted rollout
Apply the additive connector-permission migration first, deploy compatible Trigger workers, then deploy the application that exposes the two token paths. Keep this order so a CSV connection cannot be picked up by an older worker. Existing permission-aware connections continue on the administrator path until explicitly changed.