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 to see what data DX imports.

Prerequisites

To connect Bitbucket Pipelines to DX, you need:

an existing Bitbucket Cloud data connection in DX (Pipelines relies on your Bitbucket repositories in DX)
a Bitbucket credential:
- a Workspace Access Token, or
- an API Token

Note: If you are setting up Bitbucket Cloud for the first time, we recommend also setting up a Jira connection 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 connection in DX.

Step 2

Create credentials for DX with the scopes below:

If using a Workspace Access Token, include the following scopes:
- account
- pipeline
- repository
Or, if using 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/	Link
/repositories/{workspace_name}/{repo}/pipelines	Link

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.

Replace YOUR_WORKSPACE_NAME, YOUR_REPO_SLUG, and authentication credentials with your actual values before running these commands.

Choose your authentication method:

Workspace Access Token: Use -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'

API Token: Use -u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN

1. Test Workspace Repositories Access

This verifies your credentials can access repositories in your workspace:

With Workspace Access Token:

curl -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'

With API Token:

curl -u ATLASSIAN_ACCOUNT_EMAIL:API_TOKEN -H 'Accept: application/json' 'https://api.bitbucket.org/2.0/repositories/YOUR_WORKSPACE_NAME'

2. Test Pipelines Access for a Repository

Pick any repository slug from step 1 and verify you can access its pipelines:

With Workspace Access Token:

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'

With API Token:

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'

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.