Bitbucket Connection
The Bitbucket connection type enables automations to interact with Bitbucket repositories — reading branches and commits, managing pull requests, and triggering pipelines. It supports both Bitbucket Cloud and Bitbucket Data Center.
Connection Details
| Property | Value |
|---|---|
| Type ID | BITBUCKET |
| Category | Version Control Systems |
| Testable | Yes |
Friendly Example
| What you enter | Example |
|---|---|
| Connection name | Bitbucket - App Repository |
| Used for | Reading branch status and pull request approvals before a deployment workflow |
| Main details to collect | Bitbucket username, app password, and workspace name |
| Best person to provide it | Repository or workspace administrator |
After it is saved, workflow builders select Bitbucket - App Repository in a node instead of entering these details again.
Mandatory Fields
| Field | What It Means | Example |
|---|---|---|
username | The Bitbucket account username (not email address) that owns the app password. | jsmith |
appPassword | A Bitbucket app password created for the account. Encrypted at rest. Regular account passwords are not accepted. | ATBBxxxxxxxxxxxxxxxxxxxx |
workspace | The Bitbucket workspace slug — the short identifier that appears in repository URLs. | acme-corp |
Bitbucket Cloud uses app passwords, not your regular account password. App passwords are scoped credential tokens that can be revoked independently of your login password.
Advanced Fields
| Field | What It Means | Example |
|---|---|---|
baseUrl | Base URL of the Bitbucket instance. Only set this for Bitbucket Data Center (self-hosted). Leave blank for Bitbucket Cloud. | https://bitbucket.yourcompany.com |
App Password Permission Reference
| Permission Area | Access Level | When You Need It |
|---|---|---|
| Repositories | Read | Reading branches, commits, file contents |
| Repositories | Write | Creating branches, pushing commits |
| Pull requests | Read | Reading PR details and approval status |
| Pull requests | Write | Creating or updating pull requests |
| Webhooks | Read/Write | Managing webhook registrations via automation |
Setup Instructions
-
Sign in to Bitbucket Cloud and click your avatar in the bottom-left corner, then select Personal settings.
-
In the left sidebar under Security, select App passwords, then click Create app password.
-
Name the app password descriptively (e.g.,
qinfinite-automation) and select the permissions the automation requires:- Check Repositories — Read and Repositories — Write if the automation reads or modifies repository contents.
- Check Pull requests — Read (and Write if needed).
-
Click Create and copy the app password immediately. Bitbucket shows it only once.
-
Identify your workspace slug — it is the short name that appears in Bitbucket repository URLs after
bitbucket.org/(for example, inbitbucket.org/acme-corp/my-repo, the workspace isacme-corp). -
Create the connection in the Global Configurator using the username, app password, and workspace slug. Test the connection to confirm that the credentials have the expected access.
Do not use your Bitbucket account password in the appPassword field. Bitbucket Cloud rejects account passwords for API access. Always create a dedicated app password.
Troubleshooting
| Symptom | Likely Cause |
|---|---|
401 Unauthorized | The app password was entered incorrectly, has been revoked, or the username does not match the account that owns the app password |
403 Forbidden on a repository | The app password does not have the required Repositories permission, or the workspace member does not have access to that repository |
404 Not Found for a workspace | The workspace slug is wrong — check the URL of any repository in that workspace |
| Connection test fails for Data Center | The baseUrl is unreachable or the instance uses a self-signed TLS certificate |