GitLab Cloud overview

The GitLab Cloud connector indexes content from GitLab.com (SaaS) so your team can find project overviews, merge requests, code, issues, wikis, and epics through permission-aware search and Glean Assistant. Glean connects to the GitLab API over HTTPS using a group access token or a personal access token for a service account, crawls the groups and projects the token can access, and enforces GitLab's own permissions at query time so users only see what they can already see in GitLab.

For a product-level overview of the connector, see the GitLab integration page.

To connect the connector, see Setup.

Content scope and token access

A GitLab Cloud connector crawls the groups and projects that its access token can reach. It can index projects across multiple top-level groups when the token's identity supports that access. For unrelated top-level groups on GitLab.com, use a personal access token for a service account that a GitLab admin can add to every target group and project.

GitLab associates a group access token with one top-level group. To crawl projects across unrelated top-level groups, use a service-account personal access token with access to every target group and project.

If another group shares content with an invited group outside the associated top-level group, Glean cannot list the invited group's members with the group access token. Users who access the shared content through that invited group will not see those documents in Glean. Use a service-account personal access token with access to both groups for this scenario.

The connector indexes only content within the groups and projects the token can access, subject to the token's scopes and any namespace-level filters configured with help from Glean Support.

Supported objects

Glean always indexes project overviews, merge requests, code, issues, and wikis. The setup page has no toggles for these object types. Glean indexes epics by default. Clear Crawl Group Epics to exclude them.

Project overviews

• Project name and namespace.
• Project description and link to the project in GitLab.
• Default branch and star count.

Merge requests

• Merge request title, description, and state.
• Merge request comments (notes).
• Merge request diffs.
• Author, and project the merge request belongs to.

Code

• Repository file contents on the default branch, made searchable through Code Search.
• Commit messages on the default branch.

Issues

• Issue title, description, and state.
• Issue comments (notes).
• Author, and project the issue belongs to.

Wikis

• Wiki page title and body.
• Only pages whose file body is .md or .txt are indexed.

Epics

• Epic title, description, and state.

Limitations

• The connector can index projects across multiple top-level groups when the token's identity can access every target group and project. GitLab associates a group access token with one top-level group. On GitLab.com, use a service-account personal access token that a GitLab admin can add to every target group.
• Glean always indexes project overviews, merge requests (with comments and diffs), code, issues, and wikis. The Crawl Group Epics option is the only object-type toggle, and Glean turns it on by default.
• Only file content on the default branch is indexed for code and commit messages. Other branches are not crawled.
• Wiki indexing covers pages whose file body is .md or .txt; other file types in a wiki are not indexed.
• Snippets and standalone milestones are not supported.
• There are no greenlist (inclusion) or redlist (exclusion) content filters exposed in the setup UI. Namespace-level allow and block lists can be configured with help from Glean Support.
• The GitLab API does not return user email addresses, so a user-mapping CSV is required to enforce permissions correctly. See Permissions and security.

Permissions and security

How permissions are enforced

Glean mirrors GitLab's permission model. For private projects, access depends on the object type:

• Guest members can find a project overview when they can view the project in GitLab.
• Glean limits repository files, commit messages, and merge requests to members who have repository access in GitLab.

Glean reads project membership from the GitLab API and evaluates permissions at query time. Users only see GitLab content in Glean that they can access in GitLab.

Why a user-mapping CSV is required

The GitLab API does not expose user email addresses, so Glean cannot automatically map a GitLab user ID to the person's company identity (their SSO email). To bridge this, you upload a user-mapping CSV during setup that maps each numeric GitLab user ID to the corresponding company email. Without it, Glean cannot resolve GitLab memberships to Glean users and permissions cannot be enforced. See Build the user-mapping file.

Data access model

• The connector is read-only — Glean never creates, modifies, or deletes content in GitLab.
• Authentication uses a group access token or a personal access token for a service account, sent as a bearer token over HTTPS.
• The connector indexes content from the groups and projects that the token can access, subject to the token's scopes.

Crawling and freshness

Full crawls

Glean periodically re-enumerates all accessible projects and their content in a full crawl, which runs approximately every 28 days.

Incremental crawls

Between full crawls, Glean runs scheduled incremental crawls approximately hourly to pick up new and changed content.

Webhook-driven updates

When the token has the api scope and the Owner role on the relevant group, Glean automatically registers group webhooks in GitLab, so Glean reflects changes in approximately 10 minutes. Otherwise you create webhooks manually to get the same near-real-time updates. See Create webhooks manually.

Identity crawls

User and membership data is refreshed hourly so permission changes in GitLab propagate to Glean.

note

GitLab enforces API rate limits. Glean throttles its crawl to stay within those limits, backing off in response to GitLab's rate-limit responses.

Use cases and example queries

• Find a merge request by topic: "merge request adding retry logic to the billing service".
• Locate code: search a function or file name to jump straight to the implementation on the default branch.
• Recover a decision: "why did we switch the auth library" surfaces the relevant MR discussion and issue comments.
• Track work: "open issues in the payments project" or "epic for Q3 search improvements".