GitLab

By integrating GitLab with DX, you can analyze merge requests, merge request reviews, repositories, and optionally, GitLab Security Dashboard vulnerabilities. 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:

• a GitLab account that can create a Group Access Token or a Service Account
• allowlist DX IP addresses if your GitLab instance is behind a firewall or has IP restrictions

Setup instructions

Follow the steps below to connect GitLab to DX.

Data connection

Step 1

Either create a Group Access Token with the Developer role and read_api scope, or create a group service account, add it to the group with the Developer role, and create an access token with the read_api scope.

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/.

Project import filters

DX imports a GitLab project when it:

• is in a group the connection can see
• is not archived, unless Import archived projects is enabled
• is not a fork, unless Import forked projects is enabled
• is not private, unless Import private projects is enabled
• has a default branch (empty projects are skipped)

In allowlist mode, included projects are imported even when Import archived projects, Import forked projects, or Import private projects is turned off. Allow all and denylist modes still honor these settings. Projects must remain accessible to the connection and have a default branch.

If a project is missing because it is archived, forked, or private, go to DX → Admin → Data Cloud → Connections, open the GitLab connection, and review the Settings tab. Enable the corresponding import setting, or use Configure selective import to include the project in an allowlist.

Security Dashboard vulnerabilities

DX can optionally import canonical project vulnerabilities from the GitLab Security Dashboard. This data can be used in scorecards and includes results from scanners such as Semgrep when those results are uploaded to GitLab.

To import vulnerabilities:

• The top-level GitLab namespace must use the Ultimate tier.
• Scheduled vulnerability imports require GitLab 16.4 or later.
• The user associated with the access token must be able to view the Security Dashboard for the imported projects.
• The token must have the same read_api scope required by the GitLab connector.
• The GitLab Security conditional schema must be enabled for your DX account.
• For a self-hosted GitLab Data Extractor connection, use extractor version 3.17 or later.

DX performs an initial import and scheduled reconciliation through the GitLab GraphQL API. An empty result is valid when a project has no vulnerabilities visible to the token user.

Disabling the GitLab Security conditional schema stops scheduled and webhook ingestion and removes the conditional vulnerability table. If the token user loses Security Dashboard access while the schema remains enabled, DX preserves the data from the last successful import instead of treating an incomplete response as deleted data. Scorecards can continue to show that last imported state until access is restored and a successful reconciliation completes.

Troubleshooting vulnerability imports

If DX reports Unable to access GitLab Security Dashboard vulnerabilities, confirm that the namespace uses GitLab Ultimate and that the token user can view the affected project’s Security Dashboard. An empty result without an error means that no vulnerabilities are visible to the token user.

GitLab versions earlier than 16.4 do not expose every GraphQL field required by the scheduled import. Upgrade GitLab before enabling vulnerability imports. Vulnerability webhooks additionally require GitLab 17.11 or later.

Webhooks

DX supports GitLab webhooks ingestion to allow syncing merge request data and Security Dashboard vulnerability changes 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.

GitLab vulnerability webhooks became generally available in GitLab 17.11. They are sent when a vulnerability is created, its status changes, or an issue is linked to it. If the GitLab Security conditional schema is enabled, select Vulnerability events when configuring a group or project webhook.

Vulnerability webhooks provide faster incremental updates but do not contain a complete historical dataset or cover every reconciliation case. DX continues to use scheduled API imports as the source of truth.

Setting up system webhooks

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.

⚠️ Note: System hooks do not support comment or vulnerability events. To receive real-time review and vulnerability updates, set up group or project webhooks instead.

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. If the GitLab Security conditional schema is enabled, also check Vulnerability events.

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"
VULNERABILITY_EVENTS=false # Set to true when the GitLab Security conditional schema is enabled in 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,
\"vulnerability_events\": ${VULNERABILITY_EVENTS},
\"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. If the GitLab Security conditional schema is enabled, also check Vulnerability events.

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"
VULNERABILITY_EVENTS=false # Set to true when the GitLab Security conditional schema is enabled in 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,
\"vulnerability_events\": ${VULNERABILITY_EVENTS},
\"note_events\": true,
\"push_events\": false,
\"token\": \"${SECRET_TOKEN}\"
}"
done

Curl commands

When DX verifies a GitLab connection, it checks if it can access groups and merge requests. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/groups'

curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/groups/GROUP_ID/projects'

curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/projects/PROJECT_ID/merge_requests?order_by=created_at&sort=desc'

API reference

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

The following endpoints are also used by the GitLab extractor:

Errors

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

Data Cloud API

Once the initial connection is created successfully, GitLab credentials can be managed via the Data Cloud API.

• credentials.create
• credentials.update
• credentials.info
• credentials.list
• credentials.delete

Credential fields

{
  "id": 456,
  "secrets": {
    "api_token": "glpat-xxxxxxxxxxxxxxxxxxxx"
  }
}