Bitbucket Cloud Repository Configuration Fails in Bamboo with API Tokens

Summary

Bitbucket Cloud is deprecating app passwords in favor of API tokens to enhance security and provide better management controls. After September 9, 2025, users will no longer be able to create new app passwords in Bitbucket Cloud, and by June 9, 2026, all existing app passwords will stop working. Currently, Bamboo only supports Bitbucket cloud repositories (Global, Project and Plan) using app passwords for authentication. Attempts to use API tokens in Bamboo will fail, preventing users from adding new Bitbucket Cloud repositories once app passwords can no longer be created.

This article explains what this change means for Bamboo users and gives possible solutions to help keep Bamboo running. It also covers what version of Bamboo will support API tokens, how to migrate existing repositories, what to do if you can’t upgrade right away, and how to plan your transition so your builds aren’t interrupted.

Environment

Validated in Bamboo 9.6.15, 10.2.6 and 11.0.3

Diagnosis

Scenario 1: Bitbucket username and API Token are used to authenticate

This error can be seen in the Bamboo UI while fetching the repository list, as displayed in the below screenshot:

"Failed to load data from Bitbucket. 401 Unauthorized."

The following error can be observed in the Bamboo logs located at <bamboo-home>/logs/atlassian-bamboo.log:

Scenario 2: Atlassian Email and API Token are used to authenticate

The following error can be seen in the Bamboo UI when testing the connection, even though the repositories are still fetched:

The following error can be observed in the Bamboo logs located at <bamboo-home>/logs/atlassian-bamboo.log

Cause

Bamboo is currently configured to retrieve Bitbucket Cloud information using specific Bitbucket Cloud APIs that do not support authentication via API tokens. As a result, API tokens are not compatible with the current design.

Solution

Option 1: Upgrade the Bamboo Version

To address the need for API token authentication, Bamboo now supports API Token authentication starting from Bamboo versions 10.2.7, 11.0.4, and 9.6.16. Upgrading to any of these versions enables you to create repositories using API tokens, while still maintaining compatibility with existing repositories created using App Passwords until June 9, 2026. For further details, please refer to the related feature request: BAM-26156

For step-by-step instructions on creating API tokens, please refer to the official Bitbucket Cloud documentationCreate an API token | Bitbucket Cloud | Atlassian Support. After generating your API tokens, ensure you use your email address (the one associated with the API token creation) as your username, rather than your Bitbucket user ID.

Migrate the existing repositories

After upgrading to the above mentioned Bamboo version or a later, you can migrate your existing repositories by following the steps below. This will help you prevent any issues after June 9, 2026, when App Passwords are no longer supported.

1. Run the provided database query to identify repositories that are still using App Passwords for authentication.

   • If IS_GLOBAL is set to TRUE, the repository is configured at the Global Level.

   • If IS_GLOBAL is FALSE and a PROJECT_KEY is present, the repository is configured at the Project Level.

   • If IS_GLOBAL is FALSE and a FULL_KEY is present, the repository is configured at the Plan Level.

   • PostgreSQL

     SELECT v.name, v.is_global, REPLACE(v.plugin_key, 'com.atlassian.bamboo.plugins.','') AS repo_type, v.marked_for_deletion, build.full_key, build.title AS PLAN_TITLE, PROJECT.PROJECT_KEY, PROJECT.TITLE AS PROJECT_TITLE FROM vcs_location AS v LEFT JOIN plan_vcs_location ON v.vcs_location_id=plan_vcs_location.vcs_location_id LEFT JOIN build ON (build.build_id=plan_vcs_location.plan_id AND build.marked_for_deletion = false) LEFT JOIN PROJECT ON V.PROJECT_ID=PROJECT.PROJECT_ID WHERE CAST((XPATH('//serverConfiguration/entry/string[text()="repository.bitbucket.username"]/../string[2]/text()', CAST(v.XML_DEFINITION_DATA AS XML)))[1] AS TEXT) not like '%@%' AND v.PLUGIN_KEY='com.atlassian.bamboo.plugins.atlassian-bamboo-plugin-bitbucket:bbCloud';

   • MySQL

     SELECT v.NAME, v.IS_GLOBAL, REPLACE(v.PLUGIN_KEY, 'com.atlassian.bamboo.plugins.','') AS repo_type, v.marked_for_deletion, b.FULL_KEY, b.TITLE AS PLAN_TITLE, PROJECT.PROJECT_KEY, PROJECT.TITLE AS PROJECT_TITLE FROM bamboo.VCS_LOCATION AS v LEFT JOIN bamboo.PLAN_VCS_LOCATION pvl ON v.vcs_location_id=pvl.vcs_location_id LEFT JOIN bamboo.BUILD b ON (b.build_id=pvl.plan_id AND b.marked_for_deletion = false) LEFT JOIN bamboo.PROJECT ON v.PROJECT_ID=PROJECT.PROJECT_ID WHERE EXTRACTVALUE(v.XML_DEFINITION_DATA,'//serverConfiguration/entry/string[text()="repository.bitbucket.username"]/../string[2]/text()') not like '%@%' AND v.PLUGIN_KEY='com.atlassian.bamboo.plugins.atlassian-bamboo-plugin-bitbucket:bbCloud';

2. For each repository at the specified level, update the authentication details as follows:

   • Username: Use the email address linked to your API token.

   • Password: Enter the newly created or existing API token with scopes.

Option 2: Use GIT repository type

If you need additional time to upgrade but still want to use Bitbucket Cloud repositories in Bamboo, you can follow this alternative approach.

1. Instead of creating the Bitbucket Cloud repository type, create a Git repository type in Bamboo.

2. For the repository configuration:

   • Set the Repository URL to the Bitbucket Cloud repository's HTTP URL.=

   • Use x-bitbucket-api-token-auth as the username.

   • Use your API token as the password.

If the production Bamboo instance is impacted and an upgrade cannot be performed at this time due to the need for careful planning, and the Git repository type cannot be used because of its limitations, it is important to consider the potential risks to ongoing operations.

In situations where neither upgrading nor switching to the Git repository type is feasible, reaching out to the Atlassian Support team. The support team can review the specific circumstances of the environment, provide tailored guidance, and help identify the best path forward to minimize disruption and maintain business continuity.