Bitbucket Cloud Setup

Tags: Flow

Below is a step by step guide on how to integrate with Bitbucket Cloud. You can connect your account via OAuth or username and password

We strongly recommend you use a service account to create this integration. To learn how to create a service account, please see this document.

Git host permission requirements

Flow only requires read access to your repositories. This permission is needed to process the metadata used to generate our reports. 

Bitbucket Cloud does not offer the ability to narrow permissions down to just read-only access to private profile information and repositories. When connecting to Bitbucket, standard Oauth permissions include write and full admin permissions. These access levels are required in order to use Bitbucket APIs. These are never used by our system. 

Note: In order to use all services (repos, PRs, tickets) and webhooks when integrating with Flow, the service account will need to be an admin in Bitbucket.

back to top

Connect via OAuth

Connecting via OAuth is the fastest and easiest method to connect your repos and import your data, including pull requests and tickets. 

1: From your Flow homepage, go to the top navigation bar and click Settings. Using the left hand navigation under Integrations, click Integrations.

2: Click the Add Integration button in the top right hand corner of your integrations screen. 

3: On the following page, select Bitbucket from the integration provider list.

4: Under the OAuth tab, click Connect to Bitbucket.

5: If you are already logged into your Bitbucket account, a pop-up will appear prompting you to confirm access. 

Note: If you are not already logged in, you will be prompted to log in and then authorize the connection. 

6: If the connection was successful you will see the following message:

7: Once you have successfully connected, you may proceed to the Finishing up section of this document to complete the integration process. 

back to top

Connect via username and password

To connect via your Bitbucket username and password, use the Username/Password authentication method. 

1: Input your username and password then click Test connection. 

2:  If the connection was successful, you will see the following message: 

Two factor authentication

Currently, two factor authentication is not supported via username and password logins. 

If you try and connect via two factor authentication, you will see the following message :

If your account has two-factor authentication enabled, you will need to use an app password as your password. 

To set up an app password for your service account:

1, Navigate to your bitbucket settings
2, Click app passwords
3, Select the following permissions

  • Account: Read
  • Repositories: Read
  • Pull requests: Read
  • Webhooks: Read

These permissions allow Flow to use all services and webhooks.

Once complete, click create. You may now the newly created app password in the Password field in Flow. 

back to top

Finishing up

Once you have a successful connection, you can finalize your integration and begin importing repos as outlined below:

1: Click Next from the Bitbucket Authentication Method screen

2: On the next screen, select the services you want turned on. Then click Next.

Leaving all three services on allows Flow to ingest ticket data, pull request data, and repo data. You can turn services on and off at any time. 

3:  Name your integration so you can identify the connected account. Then click Create. 

4: Once you have successfully created a new Bitbucket cloud integration, you see the below message .

5:  If you see all the appropriate groups/projects under the Repos tab, that indicates that Flow has the correct access to any repos associated with these projects. To begin importing repos, click the repo import page link. 

To learn more about managing your new integration settings, see Managing integrations.

back to top

If you need help, please email for 24/7 assistance.