GitLab Cloud troubleshooting and FAQs

This page covers the most common issues seen with the GitLab Cloud connector and how to resolve them. If an issue persists after trying the remediation, contact Glean Support.

Setup and installation

Setup validation fails with an authentication error

Symptoms:

• The connector fails to save with an authentication or authorization error.
• The initial crawl does not start.

Cause	Fix
The access token is malformed or was copied incorrectly.	GitLab shows the token value only once. Generate a new access token and re-enter it. See GITLAB_3 for the full troubleshooting steps.
The token is missing required scopes or has expired.	Confirm the token carries either the api scope or the read-only scopes for the token type you chose. If it may have expired, generate a new token and re-enter it. See GITLAB_1 (users) and GITLAB_2 (projects) for the full troubleshooting steps.
The token owner cannot access the projects you expect.	Use a token that has access to every project you want Glean to crawl. See GITLAB_2 for the full troubleshooting steps.
The token reaches more than one top-level group, or the path you entered does not match.	Each connector indexes one top-level group. Scope the token to a single group, and confirm URL Path of Top Level Group matches that group's path. See GITLAB_7 for the full troubleshooting steps.
The token does not have Owner access to the top-level group.	Give the token the Owner role on the top-level group, or clear the API token has Top Level Group Owner Privileges checkbox. See GITLAB_8 for the full troubleshooting steps.

Still not resolved? Contact Glean Support.

No projects or content are indexed after setup

Symptoms:

• Setup succeeds, but few or no GitLab results appear in Glean.

Cause	Fix
The token owner does not have access to the projects.	Glean only crawls projects the token can reach. Grant the token owner access, or use a token with broader access. See GITLAB_2 for the full troubleshooting steps.
The projects are outside the configured top-level group.	Each connector indexes one top-level group. Add a separate GitLab Cloud connector for each additional top-level group you want indexed.
The initial crawl is still in progress.	The first full crawl can take time on large accounts. Wait for it to finish, then re-check. All supported objects — merge requests, code, issues, wikis, and epics — are indexed by default, so there is no per-object setting to enable.
Namespace allow/block lists are excluding projects.	If namespace filters were configured, confirm the projects fall within the allowed namespaces. Contact Glean Support to review them.

Still not resolved? Contact Glean Support.

Permissions and access

Users see the wrong GitLab content, or none at all

Symptoms:

• A user sees GitLab results they should not have access to, or is missing results they should see.

Cause	Fix
The user-mapping CSV is missing or incomplete.	The GitLab API does not return emails, so Glean relies on the user-mapping CSV to map GitLab user IDs to company emails. Upload a complete file.
The CSV uses usernames instead of numeric user IDs.	The first column must be the numeric GitLab id, not the username. Rebuild the CSV using IDs from the members API.
A permission change in GitLab has not yet propagated.	Identity data refreshes hourly. Wait for the next identity crawl, then re-check.

Still not resolved? Contact Glean Support.

Content freshness

Changes in GitLab are slow to appear in Glean

Symptoms:

• New or edited merge requests, issues, or wiki pages take a long time to show up in Glean.

Cause	Fix
Webhooks were not created.	Glean creates webhooks automatically when the token has the api scope and the Owner role on the top-level group. Otherwise you must create webhooks manually for near-real-time updates. See GITLAB_5 for the full troubleshooting steps.
The webhook secret token does not match.	The Webhook secret token in Glean must exactly match the secret token configured on the GitLab webhook. Re-enter it in both places.
Waiting for a scheduled crawl.	Without webhooks, updates arrive on scheduled incremental crawls (approximately hourly) and full crawls (approximately every 28 days).

Still not resolved? Contact Glean Support.

Code or commit content is missing

Symptoms:

• Code Search does not return files or commit messages you expect.

Cause	Fix
The content is not on the default branch.	Glean indexes code and commit messages only on the default branch. Content on other branches is not crawled.
The initial crawl is still running.	Large repositories take time to crawl. Wait for the initial crawl to complete.

Still not resolved? Contact Glean Support.

FAQs

No. The connector is read-only. It reads content, membership, and identity data, and (with the api scope) registers webhooks. It never creates, modifies, or deletes content in GitLab.

The GitLab REST API does not return user email addresses, so Glean cannot automatically match a GitLab user ID to a person's company identity. The user-mapping CSV provides that mapping so permissions are enforced correctly.

Use a token scoped to a single top-level group: either a group access token on that group (preferred) or an access token for a service account that belongs only to that group. Grant the api scope to let Glean create webhooks automatically, or keep the token read-only and create webhooks manually. Read-only scopes are read_api and read_repository for a group access token, and read_api, read_user, and read_repository for a service account token. See Create an access token.

Not with a single connector. Each GitLab Cloud connector indexes one top-level group, so add a separate connector for each group, with its own access token scoped to that group. See Top-level group scope.

No. Code Search is enabled by default after the connector is connected. See Code Search.

Merge requests (with comments and diffs), code and commit messages on the default branch, issues, wikis, and epics. Snippets and standalone milestones are not supported. See the Overview.

With webhooks configured, changes appear in approximately 10 minutes. Otherwise, updates arrive on scheduled incremental crawls (approximately hourly) and full crawls (approximately every 28 days). Identity data refreshes hourly.