By integrating Bitbucket with DX, you can analyze pull requests, repositories, and workflow data. Please visit our schema explorer to see what data DX imports—note that DX does not read or access your source code.

Prerequisites

To connect Bitbucket to DX, you need:

a Workspace Access Token
if you are not on a Premium plan and can't create a Workspace Access Token, create an App Password instead

Setup instructions

Step 1

Before setting up a connection for Bitbucket, first set up a Jira connection – this is required for identification of Bitbucket users.

Step 2

If using a Workspace Access Token, create a token for DX that includes the scopes account, pipeline, pullrequest, and repository.
If using an App Password, create an App Password for DX with all scopes set to read.

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.

Note—your workspace name should be first path in the URL (i.e., it would be myworkspace given the URL below).

https://bitbucket.org/myworkspace/myrepo/src/main/

API Reference

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

Endpoint	Documentation
/repositories/{workspace_name}	List workspace repositories
/repositories/{workspace_name}/{repository_slug}/pullrequests	List repository pull requests
/repositories/{workspace_name}/{repository_slug}/pullrequests/{pull_request_id}/activity	List pull request activity log
/repositories/{workspace_name}/{repository_slug}/pipelines	List repository pipelines
/workspaces/{workspace_name}/members	List workspace members
/repositories/{workspace_name}/{repository_slug}/commit/{sha}	Get commit
repositories/{workspace_name}/{repository.slug}/pullrequests/{pull_request.source_id}/comments	List pull requests comments

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`	Your service account does not have access to any projects or repositories.

Webhooks

DX supports Bitbucket webhooks ingestion to sync pull request data in real-time. This may be beneficial for large organizations that have difficulty keeping data up-to-date in DX through batch imports.

To enable webhook ingestion, follow the steps below:

Use the following curl command to setup bitbucket webhook

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"
      ]
    }'

For <AUTHORIZATION>,
if using a Workspace Access Token, replace it with
```
Bearer <access_token>
```
if using an App Password, replace it with
```
Basic <Base64_encoded username:password>
```
For the <URL>, enter your instance URL (yourinstance.getdx.net) followed by /webhooks/bitbucket
In place of <SECRET>, enter the provided to you by your DX account manager

Here's an example curl command:

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"
      ]
    }'

Troubleshooting

I'm seeing a `Token is invalid or not supported` error

This typically indicates that you are using a Personal API token instead of a Workspace Access Token.

Bitbucket Cloud