GitLab

GitLab Search uses Service account mode, with one self-managed project per source. Teammates do not connect personal GitLab accounts. Sim matches their verified identity to the source's permission strategy on each search and read.

Choose a permission strategy

The administrator path requires self-managed GitLab 17.4 or later and its administrator identity/settings APIs. A project Maintainer or group Owner is not an instance administrator. Non-admin mode does not require those administrator APIs.

The instance must be reachable from the Sim server and pass outbound-request protections. Use the self-managed host, not gitlab.com. Each source binds its host and project; a query cannot redirect the token elsewhere.

Add a project

1. Create a read-only PAT with the chosen scopes and an appropriate expiry.
2. Open Settings → Sources → Add source → GitLab → Add project.
3. Choose Administrator token or Non-admin token.
4. Enter the token, self-managed Host, and exact Project path or numeric ID.
5. Choose content and filters. Non-admin mode requires both CSV files below.
6. Save, then have a permitted teammate search and read known content. Repeat with a teammate who has no grant.

Use Add project again for another project. There is no initial sync. Organization membership and a matching verified email are required, but membership alone does not grant project access.

Resource settings

Sim checks returned content against these restrictions independently of the query. Available search APIs depend on the GitLab version and enabled search capabilities. Unsupported searches are reported explicitly.

Non-admin CSV permissions

Use Download template beside each field, replace the examples, and upload both files.

User mapping maps numeric GitLab user IDs to verified Sim emails:

user_id,email
123,alice@example.com
456,bob@example.com

Project permissions grants mapped users access to the project:

project_path,user_id
engineering/platform,123
engineering/platform,456

Use the full namespace path even if Project contains a numeric ID. Include inherited members explicitly. A grant without an email mapping grants nothing; rows for other projects cannot expand this source.

• Each file has exactly two columns in the shown order and at least one data row. Template headers or headerless data are accepted.
• Use UTF-8 CSV, at most 4 MiB and 100,000 data rows per file. The full request must fit 10 MiB.
• Identical rows are deduplicated. Conflicting user-ID/email mappings and malformed rows are rejected.

These grants are admin-managed authorization. A granted reader can search allowed non-confidential content; Sim does not infer that person's actual GitLab role, restrictions, or membership from the non-admin token. Update both files when access changes.

Access checks

The source token retrieves content. Administrator mode proves the reader's current GitLab identity from verified Sim email, then checks project/group membership and policy during the request. Unsupported restrictions fail closed.

Non-admin mode uses saved source-local CSV grants and revalidates the token's current host/project identity. Confidential issues are excluded, including issues that became confidential after search.

Reads recheck current settings, permissions, and metadata. A reference from another member, account, organization, project, or host cannot authorize a read. Live Search does not use a stored content or permission index.

Update permissions or rotate the token

In project settings, replace either CSV file, retaining the other when appropriate. Sim validates the resulting pair before saving. Invalid or stale updates preserve saved grants. Removed readers lose access on the next operation.

To rotate the PAT, supply its replacement in source settings. A blank token retains the saved token. Changing host, project, or permission strategy requires valid configuration for the new identity.

Troubleshooting

Related docs

• Knowledge-base connectors — separate ingestion and permission maintenance