View all connectors

Bitbucket Cloud

By integrating Bitbucket Cloud with DX, you can analyze pull requests, repositories, and pipelines data. 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 to DX, you need:

Setup instructions

Follow the steps below to connect Bitbucket Cloud to DX.

Data connection

Step 1

Before setting up a connection for Bitbucket, first set up a Jira connection—this is required for DX to identify Bitbucket users.

Step 2

  1. If using a Workspace Access Token, create a token for DX that includes the following scopes:
    • account
    • pipeline
    • pullrequest
    • repository
  2. Or, if using an API Token, create a token for DX that includes the following scopes:
    • read:repository:bitbucket
    • read:pullrequest:bitbucket
    • read:pipeline:bitbucket
    • read:workspace: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.
  • 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.

Webhooks

DX supports Bitbucket webhooks ingestion to sync pull request data in real-time. This is recommended in order to ensure real-time data accuracy in DX.

You can enable webhooks via the Bitbucket API using a curl command like below.

curl --location 'https://api.bitbucket.org/2.0/workspaces/get-dx/hooks' \
--header 'Authorization: <AUTHORIZATION>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
      "description": "",
      "url": "<URL>",
      "active": true,
      "secret": "<SECRET>",
      "events": [
        "pullrequest:created",
        "pullrequest:fulfilled",
        "pullrequest:rejected",
        "pullrequest:unapproved",
        "pullrequest:updated"
      ]
    }'

To set the value for the <AUTHORIZATION> placeholder:

  • if using a Workspace Access Token, replace it with Bearer <access_token>
  • if using an API Token, replace it with Basic <Base64_encoded atlassian_account_email:api_token>

To set the value for the <URL> placeholder, enter https://yourinstance.getdx.net/webhooks/bitbucket but uwith your unique subdomain.

To set the value for the <SECRET> placeholder, enter your webhooks secret from DX. This can be found on the Connections admin page in DX.

Here’s a full example:

curl --location 'https://api.bitbucket.org/2.0/workspaces/get-dx/hooks' \
--header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
      "description": "DX bitbucket cloud webhook setup",
      "url": "https://test.getdx.net/webhooks/bitbucket",
      "active": true,
      "secret": "a-very-secret-string",
      "events": [
        "pullrequest:created",
        "pullrequest:fulfilled",
        "pullrequest:rejected",
        "pullrequest:unapproved",
        "pullrequest:updated"
      ]
    }'

API reference

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

Endpoint Documentation
/repositories/ Link
/repositories/{workspace_name}/{repo}/pullrequests Link
/repositories/{workspace_name}/{repo}/pullrequests/{id}/activity Link
/repositories/{workspace_name}/{repo}/pipelines Link
/workspaces/{workspace_name}/members Link
/repositories/{workspace_name}/{repo}/commit/ Link
repositories/{workspace_name}/{repo}/pullrequests/{id}/comments 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 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.

Replace YOUR_WORKSPACE_NAME 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 that 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 Workspace Members Access

This verifies that your credentials can access workspace members:

With Workspace Access Token:

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

With API Token:

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

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.