---
title: "Bitbucket Cloud Commits (Default branch)"
canonical_url: "https://docs.getdx.com/connectors/bitbucket-cloud-commits-trunk/"
md_url: "https://docs.getdx.com/connectors/bitbucket-cloud-commits-trunk.md"
last_updated: "2026-05-08"
---

# Bitbucket Cloud Commits (Default branch)
By integrating Bitbucket Cloud Commits (Default branch) with DX, you can analyze pull requests, and repositories data. 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.

## Prerequisites

To connect Bitbucket Cloud Commits (Default branch) to DX, you need:

- a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/)
- if you cannot create a Workspace Access Token, create an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/) instead

## Setup instructions

Follow the steps below to connect Bitbucket Cloud to DX.

### Data connection

#### Step 1

Before setting up a connection for Bitbucket Cloud Commits (Default branch), first set up a [Bitbucket connection](https://docs.getdx.com/connectors/bitbucket-cloud/).

#### Step 2

1. If using a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), create a token for DX that includes the following scopes:
   - repository
2. Or, if using an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/), create a token for DX that includes the following scopes:
   - `read:repository:bitbucket`

#### 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.
  - If using a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), select the `API token` authentication method
  - If using an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/), select the `Basic auth` authentication method
- Please note that your workspace name should be first path in the URL, i.e., if your workspace URL is `https://bitbucket.org/myworkspace/`, your workspace name is `myworkspace`.

## API reference

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


| Endpoint | Documentation |
|--------------------------------------------------------------------------------------------------|---------------|
| repositories/{workspace_name}/{repository_slug}/commits | [Link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commits/#api-repositories-workspace-repo-slug-commits-get) |


## 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` | DX cannot access any projects or repositories. |


## Curl commands

#### When connection verification fails

When DX verifies a Bitbucket Cloud connection, it checks access to workspace repositories. 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_WORKSPACE_NAME and authentication credentials with your actual values before running these commands.</p>
  
  <div class="mb-4 p-3 bg-gray-50 rounded">
    <p class="font-medium text-sm mb-2">Choose your authentication method:</p>
    <p class="text-sm"><strong>Workspace Access Token:</strong> Use <code>-H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'</code></p>
    <p class="text-sm"><strong>API Token:</strong> Use <code>-u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN</code></p>
  </div>

  <h4>1. Test Workspace Repositories Access</h4>
  <p>This verifies that your credentials can access repositories in your workspace:</p>
  
  <p class="text-sm font-medium mb-2">With Workspace Access Token:</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 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'</code></pre>
  </div>
  
  <p class="text-sm font-medium mb-2 mt-4">With API Token:</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 -u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'</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 workspace name is correct.

**Note about Authentication**: The `-u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN` flag uses curl's built-in basic authentication, which automatically handles the Base64 encoding required for Bitbucket authentication. For workspace access tokens, use the Bearer token format as shown above.

## 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 [Bitbucket Cloud](https://docs.getdx.com/connectors/bitbucket-cloud/#credential-fields) (`settings.username`, `secrets.api_token`, or `secrets.password`).

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