--- title: "GitLab" canonical_url: "https://docs.getdx.com/connectors/gitlab/" md_url: "https://docs.getdx.com/connectors/gitlab.md" last_updated: "2026-06-18" --- # 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](https://docs.getdx.com/schema/) 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](https://docs.getdx.com/connectors/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](https://docs.gitlab.com/user/group/settings/group_access_tokens/) or a [Service Account](https://docs.gitlab.com/user/profile/service_accounts/) - allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if your GitLab instance is behind a firewall or has IP restrictions ## Setup instructions > This connector supports multiple credentials. You can add additional credentials to distribute API requests across multiple tokens, improving import speed and reliability. To learn more, go to [Can I use multiple API credentials for a data connector?](https://docs.getdx.com/knowledgebase/can-i-use-multiple-api-credentials-for-a-data-connector/) 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/. ### 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. #### 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 events. To get real-time data for GitLab reviews, 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. #### 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 ``` ## 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.

Replace YOUR_ACCESS_TOKEN and YOUR_GITLAB_URL with your actual values before running these commands.

1. Test Groups Access

This verifies that your token can access group information:

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

2. Test Group Projects Access

Replace GROUP_ID with a valid group ID to verify projects access:

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

3. Test Merge Requests Access

Replace PROJECT_ID with a valid project ID to verify merge requests access:

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. | Endpoint | Documentation | |---------------------------------------------------------------------|---------------| | graphql | [Link](https://docs.gitlab.com/api/graphql/reference/) | | `project.mergeRequests.diffStatsSummary` (GraphQL) | [Link](https://docs.gitlab.com/api/graphql/reference/#diffstatssummary) | | `project.mergeRequests(iids: [...])` (GraphQL) | [Link](https://docs.gitlab.com/api/graphql/reference/#mergerequest) | | groups | [Link](https://docs.gitlab.com/ee/api/groups.html#list-groups) | | projects | [Link](https://docs.gitlab.com/ee/api/projects.html#list-all-projects) | | projects/{projectId}/labels | [Link](https://docs.gitlab.com/ee/api/labels.html#list-labels) | | groups/{groupId}/projects | [Link](https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects) | | projects/{projectId}/merge_requests | [Link](https://docs.gitlab.com/ee/api/merge_requests.html#list-project-merge-requests) | | groups/{groupId}/members | [Link](https://docs.gitlab.com/ee/api/members.html#list-all-members-of-a-group-or-project) | | projects/{projectId}/merge_requests/{mergeRequestId}/approval_state | [Link](https://docs.gitlab.com/ee/api/merge_requests.html#get-the-approval-state-of-merge-requests) | | projects/{projectSourceId}/repository/commits | [Link](https://docs.gitlab.com/ee/api/commits.html#list-repository-commits) | | projects/{projectId}/merge_requests/{mergeRequestId}/notes | [Link](https://docs.gitlab.com/ee/api/notes.html#list-all-merge-request-notes) | The following endpoints are also used by the GitLab [extractor](https://docs.getdx.com/data-extrator/): | Endpoint | Documentation | |---------------------------------------------------------------------|---------------| | projects/{projectId}/deployments | [Link](https://docs.gitlab.com/api/deployments/#list-all-project-deployments) | | groups/{groupId}/subgroups | [Link](https://docs.gitlab.com/api/groups/#list-subgroups) | | users | [Link](https://docs.gitlab.com/api/users/#list-all-users) | | users/{userId} | [Link](https://docs.gitlab.com/api/users/#retrieve-a-single-user) | ## 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. | ## Data Cloud API Once the initial connection is created successfully, GitLab credentials can be managed via the Data Cloud API. - [credentials.create](https://docs.getdx.com/datacloudapi/methods/credentials.create/) - [credentials.update](https://docs.getdx.com/datacloudapi/methods/credentials.update/) - [credentials.info](https://docs.getdx.com/datacloudapi/methods/credentials.info/) - [credentials.list](https://docs.getdx.com/datacloudapi/methods/credentials.list/) - [credentials.delete](https://docs.getdx.com/datacloudapi/methods/credentials.delete/) ### Credential fields | Field | Type | Description | | ----- | ---- | ----------- | | `secrets.api_token` | `String` | A GitLab personal access token or group access token with `read_api` scope. | ```json { "id": 456, "secrets": { "api_token": "glpat-xxxxxxxxxxxxxxxxxxxx" } } ``` --- ## Sitemap [Overview of all docs pages](/llms.txt)