---
title: "GitLab Merge Request Commits"
canonical_url: "https://docs.getdx.com/connectors/gitlab-commits/"
md_url: "https://docs.getdx.com/connectors/gitlab-commits.md"
last_updated: "2026-06-18"
---

# GitLab Merge Request Commits
By enabling the GitLab Merge Request Commits connector, you can import metadata on individual GitLab commits and incorporate commit data in the calculation of developer time spent on tasks. 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.

Before proceeding, please make sure that you have first enabled the GitLab connector by following the steps [here](https://docs.getdx.com/connectors/gitlab/). Each GitLab-related connection in DX should utilize a separate Group Access Token to avoid rate limit issues.

## 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

Follow the steps below to connect GitLab Merge Request Commits to DX.

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

## API reference

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


| Endpoint | Documentation |
|---------------------------------------------------------------------|---------------|
| groups | [Link](https://docs.gitlab.com/ee/api/groups.html#list-groups) |
| 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) |
| projects/{projectId}/merge_requests/{mergeRequestId}/commits | [Link](https://docs.gitlab.com/ee/api/merge_requests.html#get-single-merge-request-commits) |


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


## Curl commands

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

<div>
  <p class="mb-4 text-sm text-gray-700">Replace YOUR_ACCESS_TOKEN and YOUR_GITLAB_URL with your actual values before running these commands.</p>

  <h4>1. Test Groups Access</h4>
  <p>This verifies that your token can access group information:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/groups'</code></pre>
  </div>

  <h4>2. Test Group Projects Access</h4>
  <p>Replace GROUP_ID with a valid group ID to verify projects access:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/groups/GROUP_ID/projects'</code></pre>
  </div>

  <h4>3. Test Merge Requests Access</h4>
  <p>Replace PROJECT_ID with a valid project ID to verify merge requests access:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">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'</code></pre>
  </div>

  <h4>4. Test Merge Request Commits Access</h4>
  <p>Replace PROJECT_ID and MERGE_REQUEST_IID with valid IDs to verify merge request commits access:</p>
  <div class="code-block-wrapper">
    <button class="copy-button" title="Copy to clipboard">
      <svg class="copy-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>
      <svg class="check-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>
    </button>
    <pre><code class="language-bash">curl -H 'PRIVATE-TOKEN: YOUR_ACCESS_TOKEN' -H 'Accept: application/json' 'YOUR_GITLAB_URL/api/v4/projects/PROJECT_ID/merge_requests/MERGE_REQUEST_IID/commits'</code></pre>
  </div>
</div>

If you receive a 401 Unauthorized error, your credentials are invalid. If you receive a 403 Forbidden error, your token doesn't have the required permissions. If you receive a 404 Not Found error or empty results, check that your GitLab URL and project/merge request IDs are correct.

**Note about Authentication**: The `PRIVATE-TOKEN` header is the standard authentication method for GitLab API requests. Make sure your Group Access Token has the `read_api` scope enabled.

## Data Cloud API

Once the initial connection is created successfully, credentials can be managed via the Data Cloud API. This connector uses the same credential fields as [GitLab](https://docs.getdx.com/connectors/gitlab/#credential-fields) (`secrets.api_token`).

- [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/)
---

## Sitemap

[Overview of all docs pages](/llms.txt)