GitLab Server setup

Setting up the GitLab Server connector involves these steps:

• Confirm requirements: network access, credentials, and permissions.
• Choose an authentication path: admin or non-admin personal access token.
• Create a personal access token: in GitLab, with write or read-only scopes.
• Create webhooks and a system hook: only if you chose read-only scopes.
• Build the CSV files: required only for a non-admin token.
• Configure in Glean: enter everything into the Glean Admin console.

Requirements

Technical requirements

• Your self-managed GitLab instance must be network-reachable by the Glean crawler running in your cloud. Glean supports deployments on both GCP and AWS. Contact Glean Support for any network configuration required.
• Glean connects to your instance's GitLab REST API over HTTPS.
• Glean throttles its crawl to stay within GitLab's API rate limits, backing off in response to GitLab's rate-limit responses.
• Epic crawling requires GitLab 18.1 or later.

Credential requirements

Gather these values before you start:

• Personal access token: created in GitLab (see Create a personal access token).
• GitLab instance domain: for example, https://gitlab.company.com.
• GitLab Server IP: the IP address of your instance.
• Webhook secret token: a value you choose, entered in both GitLab and Glean so Glean can verify incoming events.
• CSV files: a user-mapping CSV and a project permissions CSV, only if you use a non-admin token (see Build the CSV files).

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. Creating a system hook requires admin access to the GitLab instance.

1. Choose an authentication path

Glean supports two authentication paths. The path you choose determines which additional setup steps are required.

	Admin PAT (recommended)	Non-admin PAT
Token type	Personal access token from a GitLab admin account	Personal access token from a non-admin account with access to the projects you want Glean to crawl
User-mapping CSV	Not required — admin-scoped tokens return user emails from the GitLab API	Required — non-admin tokens do not return user emails, so a CSV mapping user IDs to emails must be uploaded
Project permissions CSV	Not required — Glean reads project memberships directly from the API	Required — non-admin tokens may not see all project members (for example, members added through groups the token user cannot access)
Webhooks	Can be created automatically with the api scope, or manually with read-only scopes	Can be auto-created for projects where the token user has Maintainer access (requires api scope); other projects require manual webhook setup

info

If you are unsure which path to use, we recommend an admin PAT. This avoids CSV uploads and ensures Glean always has complete, up-to-date permissions data.

2. 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 the account you chose in step 1 (admin or non-admin).
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 and a system hook 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.

3. Provide your instance details

You enter these in the Glean Admin console during Configure in Glean:

• Your GitLab instance domain, for example https://gitlab.company.com.
• Your GitLab Server IP.

Create webhooks and a system hook (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 webhooks for the groups or projects you want Glean to receive change events for, plus one instance-wide system hook. Group webhooks apply to all projects in a group and its subgroups; project webhooks apply to a single project.

Create webhooks

For each group or 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.

Create a system hook

A system hook lets Glean receive certain instance-level repository events.

1. In GitLab, go to Admin Area → System Hooks.
2. Create a system hook:
   • URL: copy the webhook URL shown on the GitLab connector setup page in the Glean Admin console.
   • Secret token: the same secret token you used for the webhooks.
   • Trigger: enable:
     • Push events
     • Merge request events
     • Repository update events
3. Save the system hook.

4. Build the CSV files (non-admin token only)

warning

These files are required only when the personal access token belongs to a non-admin GitLab user. If you use an admin token, skip this step — admin-scoped tokens return user emails and full membership from the GitLab API.

User-mapping CSV

A non-admin token does not return user email addresses, so Glean needs a CSV that maps each GitLab user ID to the person's company (SSO) email.

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.

Project permissions CSV

A non-admin token may return incomplete project membership — for example, members added through a group the token user cannot see. Upload a project_permissions.csv that maps projects to the users who should have access.

1. Create a CSV with two columns in the order project path, user ID. Column headers are not required.
   • The project path is the full namespace path, for example my-group/my-project.
   • Example row:
     my-group/my-project,12345
2. Keep the file — you upload it in the Glean Admin console during Configure in Glean.

note

If project memberships change, re-upload project_permissions.csv to keep permissions in sync.

Configure in Glean

Enter the values you gathered into the GitLab Server 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 Server setup. Set the connector display Name and icon.

2. Enter your instance details

Enter your GitLab instance domain (for example, https://gitlab.company.com) and your GitLab Server IP.

3. 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 and a system hook manually.

4. Enter the webhook secret token

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

5. Upload the CSV files (non-admin token only)

If you are using a non-admin token, upload the user-mapping CSV and the project permissions CSV. Skip this if you are using an admin token.

6. Choose what to index

Epics are controlled by a single setup toggle:

• Crawl epics: index epics. Selected by default. Requires GitLab 18.1 or later — clear it if your instance is older or you don't want epics indexed.

Merge requests (with comments and diffs), code, issues, and wikis are always indexed and have no per-object toggles. Code is made searchable through Code Search, which is enabled by default after the connector is connected.

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

Appendix: allow webhooks over the local network

If you want webhooks to reach Glean through your local network, allow local requests from hooks and services before creating the webhooks:

1. Go to Admin Area → Settings → Network.
2. Expand Outbound requests.
3. Under Local IP addresses and domain names that hooks and services may access, add the local proxy IP. Contact Glean Support if you need help finding this IP.
4. Select Save changes.