View all connectors

GitLab

By integrating GitLab with DX, you can analyze merge requests, merge request reviews, and repositories. Please refer to the API documentation below and 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 for each connector to avoid rate limits.

Prerequisites

To connect GitLab to DX, you need:

Setup instructions

Follow the steps below to connect GitLab to DX.

Data connection

Step 1

Create a GitLab Group Access Token to be used for DX. 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 connections page in DX and select “+ Connection” in the top right.
  • Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
    • For GitLab-hosted instances, the API base URL should be https://gitlab.com/.

Webhooks

DX supports GitLab webhooks ingestion to allow syncing merge request data in real-time. This is recommended in order to ensure real-time data accuracy in DX.

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.

If both the webhook and agent are active, there’s a chance of duplicate or inconsistent data, so we recommend disabling the agent when using webhooks. This ensures a clean, streamlined sync process.

  1. On the left sidebar of your GitLab home page, at the bottom, select Admin.
  2. Select System hooks.
  3. Click the Add a new webhook button.
  4. For the URL, enter your DX instance URL followed by /webhooks/gitlab.
  5. Enter your DX webhooks secret which can be found on the Connections admin page
  6. Uncheck Pushes
  7. Check Merge request events and Comments.

Setting up Group webhooks (via UI)

  1. Browse to the group.
  2. Go to Settings > Webhooks.
  3. Click Add a new webhook button.
  4. For the URL, enter your DX instance URL followed by /webhooks/gitlab.
  5. Enter your DX webhooks secret which can be found on the Connections admin page
  6. Uncheck Pushes
  7. 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"
WEBHOOK_URL="https://yourinstance.getdx.net/webhooks/gitlab"
SECRET_TOKEN="secret_token_from_dx"
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)

  1. Browse to the project.
  2. Go to Settings > Webhooks.
  3. Click Add a new webhook button.
  4. For the URL, enter your DX instance URL followed by /webhooks/gitlab.
  5. Enter your DX webhooks secret which can be found on the Connections admin page
  6. Uncheck Pushes
  7. 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"
WEBHOOK_URL="https://yourinstance.getdx.net/webhooks/gitlab"
SECRET_TOKEN="secret_token_from_dx"
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

API reference

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

Endpoint Documentation
groups Link
projects Link
projects/{projectId}/labels Link
groups/{groupId}/projects Link
projects/{projectId}/merge_requests Link
groups/{groupId}/members Link
projects/{projectId}/merge_requests/{mergeRequestId}/approval_state Link
projects/{projectSourceId}/repository/commits Link
projects/{projectId}/merge_requests/{mergeRequestId}/notes Link

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 API token does not have access to any projects or repositories.