---
title: "Bitbucket Pipelines"
canonical_url: "https://docs.getdx.com/connectors/bitbucket-pipelines/"
md_url: "https://docs.getdx.com/connectors/bitbucket-pipelines.md"
last_updated: "2026-05-15"
---

# Bitbucket Pipelines
By integrating Bitbucket Pipelines with DX, you can analyze your CI pipeline runs and infer deployments, without DX reading or accessing your source code. Refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports.

## Prerequisites

To connect Bitbucket Pipelines to DX, you need:

- an existing [Bitbucket Cloud](https://docs.getdx.com/connectors/bitbucket-cloud/) data connection in DX (Pipelines relies on your Bitbucket repositories in DX)
- a Bitbucket credential:
  - a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), or
  - an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)

Note: If you are setting up Bitbucket Cloud for the first time, we recommend also setting up a [Jira connection](https://docs.getdx.com/connectors/jira-cloud/) to improve user identity mapping.

## Setup instructions

Follow the steps below to connect Bitbucket Pipelines to DX.

### Data connection

#### Step 1

Ensure you have a working [Bitbucket Cloud](https://docs.getdx.com/connectors/bitbucket-cloud/) connection in DX.

#### Step 2

Create credentials for DX with the scopes below:

1. If using a [Workspace Access Token](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/), include the following scopes:
   - account
   - pipeline
   - repository

2. Or, if using an [API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/), include:
   - `read:repository:bitbucket`
   - `read:pipeline:bitbucket`
   - `read:workspace:bitbucket`

#### Step 3

- In DX, go to the connections page and select "+ Connection".
- Choose "Bitbucket Pipelines".
- Enter the credentials you created—refer to the notes below for choosing the authentication method.
  - If using a Workspace Access Token, select the `API token` authentication method (DX sends it as Bearer).
  - If using an API Token, select the `Basic auth` authentication method.
- Your workspace name is the first path segment in your Bitbucket URL. For `https://bitbucket.org/myworkspace/`, the workspace name is `myworkspace`.

### Webhooks

DX does not require Bitbucket webhooks for Pipelines. Pipeline runs are synced via the Bitbucket REST API on a schedule. No webhook configuration is needed.

## API reference

DX uses the endpoints below for Pipelines:


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


## Errors

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


| Error | Description |
|------------------------|--------------------------------------------------------------------------|
| `invalid_credentials` | Your API credentials entered are not valid. |
| `invalid_permissions` | Your API token does not have the required Pipelines/Repository scopes. |
| `no_resources` | DX cannot access any repositories in your workspace. |


## Curl commands

#### When connection verification fails

When DX verifies a Bitbucket Pipelines connection, it checks repository access and that the Pipelines endpoint is accessible. Use the curl commands below to troubleshoot.

<div>
  <p class="mb-4 text-sm text-gray-700">Replace YOUR_WORKSPACE_NAME, YOUR_REPO_SLUG, 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 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>

  <h4>2. Test Pipelines Access for a Repository</h4>
  <p>Pick any repository slug from step 1 and verify you can access its pipelines:</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/YOUR_REPO_SLUG/pipelines?pagelen=1'</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/YOUR_REPO_SLUG/pipelines?pagelen=1'</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 and repository slug are 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)