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
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 createdToken
is the personal access token
Note: If you have many GitLab projects, it may be worth using the
includes
orexcludes
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.