GitLab Connector

The GitLab connector enables indexing of merge requests, commits, and comments across your GitLab projects. Atolio supports GitLab Server (minimum version v16.5-ee) and GitLab Cloud.

Create Access Token

As an admin, perform the following steps:

• Login as admin user
• Go to https://gitlab.company.com/-/user_settings/personal_access_tokens
• Click “Add New Token”
• Give it a name and expiration date, set scope as read_api
• Copy generated token for Required Configuration Values

Setup Webhooks

If live indexing of GitLab content is desired, you will want to setup Webhooks. If you have GitLab Premium you can set up webhooks for groups. If you don’t have GitLab Premium, you need to set up a webhook for each project separately.

• Go to Settings/Webhooks
• Set URL to https://relay.{search.company.com}/connectors/gitlab/{instance}/callback/gitlab
• Set a strong “secret token”
• Check “Comments”, “Issue Events” and “Merge Request Events” under Triggers
• Keep “Enable SSL verification” checked

You also need to set up system hooks for the GitLab instance. This is done by an admin user and is required for getting live project updates.

• Go to Admin Area/System Hooks
• Set URL to the same as the webhook URL
• Set secret token as the same as the webhook secret token
• Keep “Enable SSL verification” checked

Required Configuration Values

Enter these values in the Atolio Admin console (v4.24 and later), or send them to Atolio Support (your Deployment Engineer).

Provided by Atolio: the webhook and system hook URL (https://relay.{search.company.com}/connectors/gitlab/{instance}/callback/gitlab), used for Setup Webhooks.

Keep secrets secure: Share values marked “Yes” in the Secret column only through a password-manager share (e.g. 1Password) or another secure channel agreed with Atolio Support. Never send them in plain email, chat, or support tickets.

Configuration Example

Add this block to connector-values.yaml. Replace each <PLACEHOLDER> with the matching value from the table above, and remove any line marked “Only if” that doesn’t apply.

connectors:
  gitlab:
    default:
      gitlab:
        connector: gitlab
        instance: default
        source: gitlab
        common:
          enabled: true
          identity-provider: false
        secrets:
          token:
            value: "<ACCESS_TOKEN>"
          webhook_secret:  # Only if using live indexing
            value: "<WEBHOOK_SECRET>"
        configuration:
          base-url: "<BASE_URL>"  # Only for self-hosted GitLab
          resources:  # Only for gitlab.com
            group:
              included:
                - "<GROUP_TO_INDEX>"
          username-map:  # Only for gitlab.com
            "<GITLAB_USER_ID>": "<USER_EMAIL>"

(Optional) Filter Groups

Note: If you have many GitLab projects, it may be worth using the includes or excludes feature in Atolio configuration to control the relevant projects that should be indexed.

An example inclusion/exclusion configuration will look like the following:

resources:
  group:
    included:
      - examplegroup # Index "examplegroup" from GitLab

GitLab SaaS (gitlab.com) specific configuration

If you’re using the SaaS GitLab product hosted at gitlab.com instead of a self-hosted installation you’ll need to follow the above steps to provide an inclusion filter for at least one group you’d like to index. This is necessary to prevent the connector from attempting to index the entirety of the public SaaS GitLab deployment.

Configuring GitLab user mappings

If people are using their company emails in GitLab, the identity resolver cannot automatically map them to company user identities. For this reason the GitLab configuration contains a user mapping table. For example, the entries:

'12345678':  user1@example.com
'87654321':  user2@example.com

Map two GitLab user IDs to the user’s username (i.e. email address) in the organization. The numerical GitLab ID can easily be obtained using the following URL in a browser where USERNAME is replaced with the GitLab username. The ID is in the id field of the JSON response. On the command this can be obtained by using curl and jq as follows (using the user ID USERNAME in this example):

curl 'https://gitlab.company.com/api/v4/users?access_token=ACCESS_TOKEN&search=USERNAME' | jq '.[0].id'

Adding an entry like this for every user will allow Atolio to link the GitLab user IDs to other sources.