Documentation

Bitbucket Cloud Pull Commits

By integrating Bitbucket Cloud Pull Commits with DX, you can analyze commits associated with pull requests. Please refer to the API documentation below and our schema explorer to see what data DX imports—note that DX does not read or access your source code.

Prerequisites

To connect Bitbucket Cloud Pull Commits to DX, you need:

a Workspace Access Token
if you cannot create a Workspace Access Token, create an API Token instead

Setup instructions

Follow the steps below to connect Bitbucket Cloud Pull Commits to DX.

Data connection

Step 1

Before setting up a connection for Bitbucket Cloud Pull Commits, first set up a Bitbucket connection.

Step 2

If using a Workspace Access Token, create a token for DX that includes the following scopes:
- repository
- pullrequest
Or, if using an API Token, create a token for DX that includes the following scopes:
- read:repository:bitbucket
- read:pullrequest: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, select the API token authentication method
- If using 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}/{repo_slug}/pullrequests/{pull_request_id}/commits	Link

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 pull request commits.

Curl commands

When connection verification fails

When DX verifies a Bitbucket Cloud Pull Commits connection, it checks access to workspace repositories and pull request commits. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

Replace YOUR_WORKSPACE_NAME, YOUR_REPO_SLUG, and YOUR_PR_ID 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 Pull Request Commits Access

This verifies that your credentials can access pull request commits:

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/pullrequests/YOUR_PR_ID/commits'

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/pullrequests/YOUR_PR_ID/commits'

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, repository slug, and pull request ID 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 (settings.username, secrets.api_token, or secrets.password).