By integrating GitLab with DX, you can analyze merge requests, merge request reviews, and repositories. Please visit our schema explorer to see what data DX imports—note that DX does not read or access your source code.

In addition to the GitLab connector, you can setup the additional GitLab Pipelines connector—please use a separate API token to avoid rate limiting.

Prerequisites

To connect GitLab to DX, you need:

a GitLab account that can create a Group Access Token
if your GitLab instance is behind a firewall or has IP restrictions, you need to allowlist DX IP addresses

Setup instructions

Follow the steps below to connect GitLab to DX.

Step 1

Create a GitLab group access token to be used for the DX Data Cloud connection. Select Developer as the role and enable the read_api scope to grant API read access.

Step 2

Grant the Group access to projects that you want to import.

Step 3

Navigate to the connector setup form in DX.
Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.

For GitLab-hosted instances, the GitLab API base URL should be https://gitlab.com/ without an organization name to the URL.

API Reference

The table below lists the specific API endpoints that are used by DX.

Endpoint URL	Link to Endpoint Documentation	Permissions Needed
groups	List Groups	Group access token with read_api scope
projects	List All Projects	Group access token with read_api scope
projects/#{project_id}/labels	List a Project Labels	Group access token with read_api scope
groups/#{group_id}/projects	List a Group's Projects	Group access token with read_api scope
projects/#{project_id}/merge_requests	List Project Merge Requests	Group access token with read_api scope
groups/#{group_id}/members	List All Members of a Group or Project	Group access token with read_api scope
projects/#{project_id}/merge_requests/#{merge_request_id}/approval_state	Get the Approval State of Merge Requests	Group access token with read_api scope
projects/#{project_source_id}/repository/commits	List Repository Commits	Group access token with read_api scope
projects/#{project_id}/merge_requests/#{merge_request_id}/notes	List All Merge Request Notes	Group access token with read_api scope

Errors

The table below lists potential error codes when adding a connection in DX.

Error	Description
`invalid_credentials`	Your API credentials entered are not valid.
`invalid_permissions`	Your API token does not have the permissions required by DX.
`no_resources`	Your service account does not have access to any projects or repositories.

Webhooks

DX supports GitLab webhooks ingestion to allow syncing merge request data in real-time. This may be beneficial for large GitLab organizations that are difficult to keep up-to-date in DX through API-based data imports.

All three types of GitLab subscriptions—GitLab.com, GitLab Dedicated, and GitLab self-managed—have the option to configure GitLab webhooks at both the project-level and group-level. GitLab self-managed also has the option to configure Gitlab webhooks at the system level.

Setting up system webhooks (recommended)

On the left sidebar of your GitLab home page, at the bottom, select Admin.
Select System hooks.
Click Add a new webhook button.
For the URL, enter your instance URL followed by /webhooks/gitlab.
Enter the secret provided to you by your DX account manager.
Uncheck Pushes and check Merge request events and Comments.

Setting up Group webhooks (via UI)

Select the group.
Go to Settings -> Webhooks.
Click Add a new webhook button.
For the URL, enter your instance URL followed by /webhooks/gitlab.
Enter the secret provided to you by your DX account manager.
Uncheck Pushes and check Merge request events and Comments.

Setting up Group webhooks (via CLI)

# Replace these variables with your own values
GITLAB_URL="https://gitlab.com"
ACCESS_TOKEN="your_personal_access_token" # Replace with your GitLab personal access token
WEBHOOK_URL="https://yourinstance.getdx.net/webhooks/gitlab" # Replace "yourinstance"
SECRET_TOKEN="secret_token_from_dx" # Replace with secret provided by your DX account manager
GROUP_IDS=("123" "456" "789") # Replace with your GitLab group IDs

# Loop over group IDs and create webhooks
for GROUP_ID in "${GROUP_IDS[@]}"; do
curl --request POST "${GITLAB_URL}/api/v4/groups/${GROUP_ID}/hooks" \
--header "PRIVATE-TOKEN: ${ACCESS_TOKEN}" \
--header "Content-Type: application/json" \
--data "{
\"url\": \"${WEBHOOK_URL}\",
\"merge_requests_events\": true,
\"note_events\": true,
\"push_events\": false,
\"token\": \"${SECRET_TOKEN}\"
}"
done

Setting up Project webhooks (via UI)

Select the project.
Go to Settings -> Webhooks.
Click Add a new webhook button.
For the URL, enter your instance URL followed by /webhooks/gitlab.
Enter the secret provided to you by your DX account manager.
Uncheck Pushes and check Merge request events and Comments.

Setting up Project webhooks (via CLI)

# Replace these variables with your own values
GITLAB_URL="https://gitlab.com"
ACCESS_TOKEN="your_personal_access_token" # Replace with your GitLab personal access token
WEBHOOK_URL="https://yourinstance.getdx.net/webhooks/gitlab" # Replace "yourinstance"
SECRET_TOKEN="secret_token_from_dx" # Replace with secret provided by your DX account manager
PROJECT_IDS=("123" "456" "789") # Replace with your GitLab project IDs

# Loop over project IDs and create webhooks
for PROJECT_ID in "${PROJECT_IDS[@]}"; do
curl --request POST "${GITLAB_URL}/api/v4/projects/${PROJECT_ID}/hooks" \
--header "PRIVATE-TOKEN: ${ACCESS_TOKEN}" \
--header "Content-Type: application/json" \
--data "{
\"url\": \"${WEBHOOK_URL}\",
\"merge_requests_events\": true,
\"note_events\": true,
\"push_events\": false,
\"token\": \"${SECRET_TOKEN}\"
}"
done