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.

Likely cause	Remediation
The personal access token was copied incorrectly or has expired.	GitLab shows the token value only once. Generate a new personal access token and re-enter it.
The token is missing required scopes.	Confirm the token has either the api scope or the read-only trio read_user, read_api, read_repository.
The token owner cannot access the projects you expect.	Use a token from an account that has access to every project you want Glean to crawl.

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.

Likely cause	Remediation
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.
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.

Likely cause	Remediation
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.

Likely cause	Remediation
Webhooks were not created.	With the api scope Glean creates webhooks automatically. With read-only scopes you must create webhooks manually for near-real-time updates.
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.

Likely cause	Remediation
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.

Grant the api scope to let Glean create webhooks automatically, or grant the read-only trio read_user, read_api, and read_repository and create webhooks manually.

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.