GitLab Cloud setup

Setting up the GitLab Cloud connector involves these steps:

• Confirm requirements: the GitLab access, credentials, and permissions you need.
• Create an access token: in GitLab, with access to the groups and projects Glean should crawl.
• Create webhooks manually: only if your token cannot create them automatically.
• Build the user-mapping file: a CSV mapping GitLab user IDs to company emails.
• Configure in Glean: enter everything into the Glean Admin console.

Requirements

Technical requirements

• Glean connects to the GitLab REST API at https://gitlab.com/api/v4/ over HTTPS.
• Glean throttles its crawl to stay within GitLab's API rate limits, backing off in response to GitLab's rate-limit responses.
• The connector can index projects across multiple top-level groups when the access token can reach them.

Credential requirements

Gather these values before you start:

• Access token: a group access token or a personal access token for a service account that can access every group and project Glean should crawl (see Create an access token).
• Webhook secret token: a value you choose, entered in both GitLab and Glean so Glean can verify incoming webhook events.
• User-mapping CSV: a file mapping GitLab user IDs to company emails (see Build the user-mapping file).

Permission requirements

• The token must reach every group and project you want Glean to crawl.
• For Glean to create group webhooks automatically, the token needs the api scope and the Owner role on the relevant group.
• To create webhooks manually, you need the Maintainer role for a project or the Owner role for a group.

1. Create an access token

Use a token whose identity can access every group and project you want to index. A group access token belongs to one top-level group. For unrelated top-level groups on GitLab.com, use a personal access token for a service account that can be granted membership in every target group and project.

Option A: Group access token (preferred)

1. In GitLab, go to a group you want Glean to crawl → Settings → Access tokens → Add new token.
2. Give it a name, for example Glean GitLab Connector.
3. Set Role to Owner. This is required for Glean to create webhooks automatically.
4. Choose the scopes:
   • To let Glean create webhooks automatically, grant the api scope.
   • To keep the token read-only, grant read_api and read_repository. You must then create webhooks manually.
5. Set an Expiration date per your policy. GitLab requires an expiry.
6. Select Create and copy the token value. GitLab shows it only once.

See Group access tokens in the GitLab docs.

Group access-token limitation

A group access token can list members only from its associated top-level group. If another group shares content with an invited group outside that 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 token whose identity can access both groups for this scenario.

Option B: Personal access token for a service account

1. Create or select a service account supported by GitLab. It must be capable of membership in every target top-level group and project. On GitLab.com, use a personal access token for the service account that can be added to each target top-level group.
2. Add the identity to the groups you want Glean to crawl. Use the Owner role where Glean should create group webhooks automatically.
3. Next to the service account, select (…) → Manage access tokens → Add new token.
4. Give it a name, for example Glean GitLab Connector.
5. Choose the scopes:
   • To let Glean create webhooks automatically, grant the api scope.
   • To keep the token read-only, grant read_api, read_user, and read_repository. You must then create webhooks manually.
6. Set an Expiration date per your policy. GitLab requires an expiry.
7. Select Create and copy the token value. GitLab shows it only once.

Make sure the identity can access every group and project you intend to index. For multiple unrelated top-level groups, verify that it is a member of each target group before creating the token.

note

If you grant read-only scopes, clear the API token has write privileges checkbox in the Glean Admin console during Configure in Glean.

2. Create webhooks manually

Skip this step when your token has the api scope and the Owner role on the relevant group — Glean creates the group webhooks for you.

Otherwise, create a webhook for each group or project you want Glean to receive change events for. Group webhooks apply to all projects in a group and its subgroups; project webhooks apply to a single project.

1. Go to the group or project → Settings → Webhooks → Add new webhook.
2. Configure the webhook:
   • URL: copy the webhook URL shown on the GitLab connector setup page in the Glean Admin console.
   • Secret token: the webhook secret token you enter in Glean.
   • Trigger: enable:
     • Push events
     • Comments
     • Issues events
     • Confidential issues events
     • Merge request events
     • Wiki page events
     • Repository update events
3. Select Add webhook.

3. Build the user-mapping file

The GitLab API does not return user email addresses, so Glean requires a CSV that maps each GitLab user ID to the person's company (SSO) email. This file is required for the GitLab Cloud connector.

1. Create a CSV with two columns in the order user ID, email. Column headers are not required.
   • The user ID is the numeric id from the GitLab API — not the username. Retrieve IDs with the members API.
   • Example row:
     12345,user1@example.com
2. Keep the file — you upload it in the Glean Admin console during Configure in Glean.

You can source company emails from your identity provider (for example, Okta or Google Workspace).

4. Configure in Glean

Enter the values you gathered into the GitLab Cloud connector setup page in the Glean Admin console, in this order.

1. Start connector setup

In the Glean Admin console, go to Connectors, add the GitLab connector, and select the GitLab Cloud setup. Set the connector display Name and icon.

2. Enter the access token

Paste the access token into the Access token field.

3. Enter the webhook secret token

In the Webhook secret token field, enter the same secret token value you used when creating webhooks. This lets Glean verify that incoming webhook events came from your GitLab instance.

4. Set the token privilege checkboxes

• API token has owner privileges: keep this selected if the token has the Owner role on the relevant group where Glean should create group webhooks automatically. Clear it otherwise.
• API token has write privileges: select this if the token has the api scope so Glean creates webhooks automatically. Leave it cleared for read-only scopes, and make sure you have created webhooks manually.

5. Upload the user-mapping file

Upload the user-mapping CSV so Glean can map GitLab user IDs to company emails and enforce permissions.

6. Save and start the initial crawl

Select Save. Glean validates the connection before saving it, then starts the initial crawl. Once it completes, GitLab content appears in Glean search results for users who have access to it.

If validation fails, the connector is not saved — fix the reported problem and select Save again.

Glean indexes merge requests (with comments and diffs), code, issues, and wikis by default, and these object types have no per-object toggles. Epics are also indexed by default, controlled by the Crawl Group Epics toggle on the setup page — leave it selected to index epics, or clear it to skip them. Code is made searchable through Code Search, which is enabled by default after the connector is connected.

Select code files to index

In the connector's Manage data tab, under Additional Crawl Settings:

Use Code file types to index body to select supported file extensions or add custom extensions, such as .py or .md.

Use Code files to index body to enter an exact filename. This can be a file without an extension, such as Dockerfile, a file with an extension, such as skill.md, or a dot-prefixed filename, such as .gitignore. Glean matches the value with the repository file name after removing its directory path. To match every filename ending in .dockerfile, add .dockerfile under Code file types to index body. Enter multiple filenames as comma-separated values. Filename matching is case-insensitive.

These connector-level settings control code-body indexing and searchability for repositories in the groups and projects the token can reach. Code Search remains enabled by default after you connect the connector.

API endpoints reference

Glean uses the following GitLab REST API endpoints to crawl content and identity data.

Endpoint	Description
GET /api/v4/users	List users for identity crawling
GET /api/v4/groups	List groups the token can access
GET /api/v4/projects	List projects the token can access
GET /api/v4/projects/<id>/members/all	List project members (permissions)
GET /api/v4/projects/<id>/wikis	List and fetch wiki pages
GET /api/v4/projects/<id>/issues	List issues
GET /api/v4/projects/<id>/merge_requests	List merge requests
GET /api/v4/projects/<id>/merge_requests/<id>/notes	List merge request comments
GET /api/v4/projects/<id>/merge_requests/<id>/diffs	Fetch merge request diffs
GET /api/v4/projects/<id>/repository/commits	Fetch commit messages on the default branch