GitLab Connector

Index merge requests, commits, and comments in your GitLab projects.

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

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

Provide Configuration

With the Access Token and Webhook Secret in hand, provide these configuration values to your Deployment Engineer:

  • BaseURL is left blank when using gitlab.com. For self-hosted installations specify the base URL for your instance, e.g. gitlab.example.com
  • WebhookSecret is the webhook secret previously created
  • Token is the personal access token

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.