GitLab Cloud setup

Setting up the GitLab Cloud connector involves four steps:

• Confirm requirements: the GitLab access, credentials, and permissions you need.
• Create a personal access token: in GitLab, with either write or read-only scopes.
• Create webhooks manually: only if you chose read-only scopes.
• 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.

Credential requirements

Gather these values before you start:

• Personal access token: created in GitLab (see Create a personal 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 account that creates the personal access token must have access to every project you want Glean to crawl.
• To create webhooks manually, you need the Maintainer role for a project or the Owner role for a group.

1. Create a personal access token

Glean authenticates to GitLab with a personal access token (PAT). The scopes you grant determine whether Glean can create webhooks automatically.

1. Sign in to GitLab with an account that can access every project you want Glean to crawl.
2. Go to your avatar in the top right → Edit profile → Access tokens.
3. Select Add new token and give it a name, for example Glean Token.
4. Choose the scopes:
   • To let Glean create webhooks automatically, grant the api scope.
   • To keep the token read-only, grant read_user, read_api, and read_repository. With read-only scopes you must create webhooks manually.
5. Leave Expiration date empty so the token does not expire.
6. Select Create personal access token and copy the token value. GitLab shows it only once.

note

If you grant the read-only scopes (read_user, read_api, read_repository), clear the write privileges checkbox in the Glean Admin console during Configure in Glean.

Create webhooks manually (read-only scopes only)

Skip this step if your token has the api scope — Glean creates the webhooks for you.

If your token has only read-only scopes, 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 needs 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).

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 Data sources, add the GitLab connector, and select the GitLab Cloud setup. Set the connector display Name and icon.

2. Enter the personal access token

Paste the personal access token into the token field.

• If the token has the api scope, select the write privileges checkbox so Glean creates webhooks automatically.
• If the token has read-only scopes, leave write privileges cleared and make sure you have created webhooks manually.

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. Upload the user-mapping file

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

5. Save and start the initial crawl

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

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 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.

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/projects	List accessible projects
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