Bitbucket connection
Refer to the Early Access page to view current programs and request Early Access for a specific feature.
Bitbucket Cloud is Atlassian's Git hosting and CI/CD service. Connect Bitbucket to Data Integration to sync one workspace's documentation files, with their full content, into your data warehouse or Knowledge Hub, along with engineering data: repositories, projects, workspace members, pull requests and their activity, commits, branches, pipelines and their steps, deployments, and deployment environments.
The connector supports Bitbucket Cloud only, not Bitbucket Data Center.
Prerequisites
- A Bitbucket Cloud workspace, and its Workspace ID: the part after
bitbucket.org/when you open the workspace, for exampleacmeinbitbucket.org/acme. - Read access to the repositories you want to sync.
Authentication methods
You choose one of two credentials types when you create the connection:
- Basic Auth (Atlassian API token): your Atlassian account email and a scoped API token. Recommended for most teams. The token belongs to a person, so the connection sees what that person can see.
- Bearer (access token): a workspace, project, or repository access token. It isn't tied to a person, and it's the only way to get Bitbucket's higher rate limits (see Rate limits).
Bitbucket app passwords no longer work. Atlassian removed them on 28 July 2026. Use an API token or an access token instead.
Retrieving your credentials from Bitbucket
Option A: Create an Atlassian API token
-
Sign in to your Atlassian account settings and go to Security > API tokens.
-
Select Create API token with scopes, give it a name and an expiry date, and choose Bitbucket.
-
Select all of these scopes. Each one is required, and none includes another:
read:repository:bitbucketread:pullrequest:bitbucketread:pipeline:bitbucketread:project:bitbucketread:workspace:bitbucket
-
Copy the token and store it securely. You can't see it again after you close the dialog.
API tokens expire after at most a year. Note the expiry date so you can replace the token before it expires.
Option B: Create an access token
- In Bitbucket, open the settings of the repository, project, or workspace you want to sync, and go to Security > Access tokens. Repository access tokens are available on every plan; project and workspace access tokens need Bitbucket Premium.
- Select Create access token and grant read access to Repositories, Pull requests, Pipelines, Projects, and Account.
- Copy the token and store it securely.
A repository access token only sees its own repository. To sync several repositories with one connection, use a workspace or project access token, or an API token.
Connecting Bitbucket to Data Integration
-
Navigate to the Data Integration console.
-
Select Connections, then select + New Connection.
-
Search for and select Bitbucket as the connection type.
-
Enter a Connection Name to identify this connection.
-
Under Credentials Type, select Basic Auth or Bearer, then fill in the fields:
Credentials type Field Value Basic Auth Workspace ID Your workspace ID, for example acmeAtlassian account email The email you sign in to Atlassian with, not your Bitbucket username API token The token from option A Bearer Workspace ID Your workspace ID Access token The token from option B -
Select Test Connection. The test lists the workspace's repositories, so it also checks the workspace ID and the token's access.
-
Select Save to finish creating the connection.
You choose which repositories to sync when you build a data flow, not on the connection. See Bitbucket walkthrough.
Rate limits
Bitbucket allows 1,000 API calls per hour for repository data on an API token, shared with everything else that person runs. On Standard and Premium plans with 100 or more paid users, an access token gets up to 10,000 calls per hour.
When the limit is reached, the run waits and retries until the hour rolls over, rather than failing. Documentation files cost the most calls, about 2 per file on every run:
| Documentation files | Calls per run | Time on an API token |
|---|---|---|
| 200 | About 410 | Well within one hour |
| 2,000 | About 4,050 | About 4 hours |
| 10,000 | About 20,200 | About 20 hours. Use an access token or a narrower folder. |
Notes
- Bitbucket Cloud only. Bitbucket Data Center and Server aren't supported.
- Documentation Files reloads every matching file on every run. Bitbucket has no feed of changed files the connector can use yet. Set a narrow Folder to keep runs short.
- Commits, Branches, Pipelines, Pipeline Steps, Deployments, Environments, and Workspace Members are full loads on every run. Bitbucket can't filter commits or pipelines by date.
- Workspace Members doesn't include email addresses. Bitbucket doesn't expose them.
- A documentation file that isn't UTF-8, or that fails to download, is skipped. The other files in the repository still load, and skipped files show in the run log.
If you need a report or object that isn't currently supported, contact support so it can be evaluated for a future release.
Troubleshooting
| Error | Likely cause |
|---|---|
| 401 Unauthorized | Wrong email or token, an expired token, or an app password. For an API token, the email must be your Atlassian account email. |
| 403 Forbidden | The token is missing a scope, or the person behind it can't see the repository. Check the scopes in option A. |
| 404 Not Found on Test Connection | The Workspace ID is wrong. Use the slug from bitbucket.org/WORKSPACE, not the workspace's display name. |
| 429 Too Many Requests in the logs | The hourly rate limit was reached. The run waits and continues. |
| HTTP 555 on Documentation Files | Bitbucket timed out walking a large folder tree. Set a narrower Folder or a lower Folder depth. |
| A repository returns no documentation files | Folder doesn't exist in that repository, no file matches File filter, or the repository has no branch named Branch. |