Authentication mechanism & required credentials

The GitLab connector uses Personal Access Token (PAT)-based authentication to securely access GitLab APIs and fetch repository content, discussions, issues, documentation, and source code.

Required Credentials

API permissions required

The Personal Access Token must have the following scope:

Scope

This is the simplest configuration for most deployments.

Read-only alternative (least privilege)

For organizations that prefer restricted read-only access, the following scopes can be used instead of api:

This configuration is suitable when write access is not permitted by organizational security policies.

Admin requirements

Required access level

GitLab administrator or authorized user access

An administrator or authorized GitLab user account is required to:

• Generate Personal Access Tokens

• Access repositories and groups in scope

• Allow API-based crawling of GitLab content

• Configure repository visibility and permissions

Prerequisites

• GitLab instance must support REST API access

• API endpoints must be accessible from the connector environment

• The GitLab user account must have access to all required projects and groups

• Repositories, merge requests, issues, and wikis must be enabled within GitLab projects

• Optional: User identity mapping CSV may be required if GitLab user emails are hidden or unavailable through APIs

Setup instructions

Generate personal access token

1. Log in to your GitLab instance.

2. Navigate to User Settings

   1. Click on your profile picture at top right → Preferences
      

   2. This will open the User Settings page 
      

3. Go to Access → Personal access token
   

4. Click Add new token or Generate token

5. Configure the token:

   • Token name: Example: Enterprise Search Connector

   • Expiration date: Set an appropriate expiration date (recommended)

   • Scopes: Select:

     • api (Recommended)

     • For organizations that prefer restricted read-only access, the following scopes can be used instead of api:

       • read_user

       • read_api

       • read_repository

6. Click Create personal access token

7. Copy and securely store the generated token immediately
   (The token cannot be retrieved again after creation)

User identity mapping (optional)

In some GitLab environments, user email addresses may not be accessible through APIs due to:

• Privacy settings configured in GitLab

• SSO/SAML-based authentication setups

• Restricted user profile visibility

• Self-managed GitLab instances with limited user data exposure

In such scenarios, an optional user mapping CSV may be required to map GitLab usernames or user IDs to enterprise user email addresses.

Example CSV format

Purpose

The mapping file helps:

• Associate GitLab activity with enterprise users

• Improve ownership attribution in search results

• Support access control and user resolution workflows

• Ensure consistent identity mapping across systems

When this is typically required

• GitLab APIs do not return user email addresses

• Users have private email visibility enabled

• External identity providers manage authentication

Connector configuration schema

Authentication & authorization notes

• The connector requires a Personal Access Token from a GitLab user account to authorize API calls.

• The associated GitLab account must have access to all repositories, groups, and projects intended for crawling.

• Repository visibility and permissions configured in GitLab determine which content can be indexed and searched.

• The connector uses GitLab APIs to fetch:

  • Merge request descriptions

  • Merge request conversations/comments

  • Issues

  • Wikis

  • Commit messages from the main branch

  • Source code

  • Documentation files (.md, .txt)

• Optional user mapping CSV support helps resolve enterprise user identities when GitLab email visibility is restricted.