Bitbucket Cloud

The information below applies to repositories hosted on Bitbucket Cloud. It explains how to grant Hackolade Studio access to your Bitbucket account, which is a pre-requisite for using the features "submit for review" and "review change requests".

 

 

IMPORTANT: as of September 9, 2025, app passwords can no longer be created. Use API tokens with scopes instead.  All existing app passwords will be disabled on June 9, 2026.  Migrate any integrations before then to avoid disruptions.  While starting with v8.4.2, the Hackolade Studio dialog is updated to reflect the Bitbucket change to API tokens with scopes, it is possible to use older application versions to connect to Bitbucket Cloud.

 

 

API Tokens with scopes, using v8.4.2 and above

API tokens are designed to be used for a single purpose with limited permissions, so they don't require two-factor authentication (2FA).  API tokens are tied to an individual account's credentials and should not be shared. By sharing your API token you're giving direct, authenticated access to everything that the token has permissions to do with the Bitbucket APIs.  Bitbucket API tokens are further described in this link.

 

 

 

 

To create a connection to Bitbucket Cloud, go to Repository > Repository Connections, then:

 

• In the Provider dropdown, select Bitbucket (not Bitbucket Data Center).

• The Host domain name should be bitbucket.org (not editable).

• The Connect with dropdown should be App password (not editable).

• The email address is the address that you use to connect to Bitbucket Cloud
   

• The API token with scopes generated following these instructions.

  • Click the Generate link to create an API token with scopes, or go to https://id.atlassian.com/manage-profile/security/api-tokens

  • WARNING: an simple API token will NOT work if is not created with scopes, so make sure to click the button Create API token with scopes.
    
     

    • Provide a name and expiration date that cannot be more than 365 in the future
      

    • Select the app Bitbucket
      
       

    • Select the scopes

      • The following scopes must all be selected:

•  

  •  

    •  

      •  

        • read:pullrequest:bitbucket
        • read:repository:bitbucket
        • read:user:bitbucket
        • read:workspace:bitbucket
        • write:pullrequest:bitbucket
        • write:repository:bitbucket

      • It is suggested to proceed in 2 steps, first for read scopes (make sure to list all the read scopes and select the 4 that are necessary)
        

      • then for write scopes
        
         

      • Review your settings and create the token
        
         

      • Copy your token, save it in a safe place for possible future reference and paste it in the Hackolade Studio dialog
        

 

 

API Tokens with scopes, using a version of Hackolade Studio prior to v8.4.2

API tokens are designed to be used for a single purpose with limited permissions, so they don't require two-factor authentication (2FA).  API tokens are tied to an individual account's credentials and should not be shared. By sharing your API token you're giving direct, authenticated access to everything that the token has permissions to do with the Bitbucket APIs.  This is further described in this link.

 

To create a connection to Bitbucket Cloud, go to Repository > Repository Connections, then:

 

• In the Provider dropdown, select Bitbucket (not Bitbucket Data Center).
• The Host domain name should be bitbucket.org (not editable).
• The Connect with dropdown should be App password (not editable).
• The Username should be filled in with the email address that you use to connect to Bitbucket Cloud (i.e. not your username anymore). The hint that pops up can be ignored.

 

• The App password should be filled in with an API token with scopes.

  • Follow this link to create an API token with scopes: https://id.atlassian.com/manage-profile/security/api-tokens
  • WARNING: it will NOT work if you provide a simple API token (with no scopes), so make sure to click the button Create API token with scopes.
  • The following scopes must all be selected:

•  

  •  

    • read:pullrequest:bitbucket
    • read:repository:bitbucket
    • read:user:bitbucket
    • read:workspace:bitbucket
    • write:repository:bitbucket
    • write:pullrequest:bitbucket

 

 

App passwords

In the repository connection manager, you first need to provide your Bitbucket username (it is displayed on your Bitbucket profile). Note that using your email address as username does NOT work.

 

 

You must provide an app password, which is a complex password generated by Bitbucket Cloud.  Click on the "generate" link located to the right of the input field to navigate to the app password creation form. Give a meaningful name to your new app password - e.g. "Hackolade Studio" - and select the permissions "Account:Read" and "Pull requests:Write".

 

 

Click on the "Create" button and copy-paste the generated password in Hackolade Studio. As a last step, click on "Connect" in Hackolade Studio and you are all set!

You can find more information about app passwords in the Bitbucket Cloud documentation.

 

Remarks: To be able to retrieve the list of eligible reviewers for a pull request, you must belong to a user group. If you cannot get access to that list in Hackolade, contact your Bitbucket administrator and ask to be added to a user group.

 

You may get the error message below if you didn't set a valid app password.  It can also indicate that your app password has been revoked, or that it does not grant enough permissions to Hackolade Studio.

 

 

If you see this message, please follow the instructions above.