Bitbucket - do not use yet

Integrate Bitbucket Cloud with OX to centralize repository security findings alongside container, pipeline, cloud, and runtime signals already in OX.

OX scans Bitbucket repositories on a schedule and on demand, enriches findings with OX context (application mapping, workflows, and compliance), and presents a unified queue for investigation and reporting.

missing active issues image

What OX adds

• Context and correlation: OX maps Bitbucket findings to applications, services, and teams to show impact and ownership.

• Prioritization with severity factors: OX may reprioritize scanner severities when exploitability and environment context reduce risk (for example, Critical → High). Severity factors explain why the priority changed.

• Evidence at a glance: When available, OX displays scanner evidence, file locations, and remediation guidance alongside OX analytics to speed triage.

Terminology mapping

Bitbucket and OX use different labels for similar concepts. Use this quick map while you work.

Bitbucket Cloud	OX Security
Pipelines	CI/CD Pipelines
Repositories	Applications

Connection methods

For general information about connection methods, see the article Connection methods.

There are three options to connect Bitbucket Cloud to OX.

Connection Method	Details
Bitbucket App (recommended)	Use the OX-created application for streamlined connection with app-level permissions. Simplifies installation and authorization.
Identity Provider	Use your existing connection for centralized authentication.
User name and token	This method replaced connecting with a user name and password.

Prerequisites

Prerequisites for all connection methods

Prerequisite	Description
OX permissions	Permission to configure connectors
Bitbucket Cloud access	Access to the Bitbucket Cloud workspace(s) you want to connect

Additional prerequisites by connection method

Connection Method	Prerequisites
Bitbucket app	Permission to install apps in the workspace
Identity Provider (IdP)	Access to Bitbucket Cloud using an OAuth connection and Bitbucket Cloud administrator access
User name and token	Bitbucket account with permission to generate tokens

Connect with the OX Bitbucket app

The Bitbucket App method uses an OX-created application to simplify connection. The app requests read access to repositories and branches, pull requests, and pipeline configuration results.

1. Verify that the prerequisites are in place.

2. In OX, go to Connectors and select Bitbucket Cloud > BITBUCKET APP.

   
3. Select CONNECT. OX validates the credentials.

4. The Grant access dialog opens.

   
5. In Configure your Bitbucket Cloud connector, select the repos you want OX to scan.

   
6. Select SAVE.

7. In Configure your Bitbucket Cloud credentials, select VERIFY CONNECTIVITY.

   

A green success message at the bottom of the screen indicates a successful connection. If verification fails, check your credentials and permissions.

Optional configurations

• To change the repositories OX scans and monitors, see the section Change the repositories OX scans.

• To connect more Bitbucket accounts to the same organization in the OX platform, see the section Connect multiple Bitbucket accounts.

Connect with Identity Provider

1. Verify that the prerequisites are in place.

2. In OX, go to Connectors and select Bitbucket Cloud > IDENTITY PROVIDER.

   
3. Select CONNECT. OX validates the credentials.

4. In Confirm access to your account, select Grant access.

   
5. In Configure your Bitbucket connector, select the repos you want OX to scan.

   
6. Select SAVE.

7. In Configure your Bitbucket credentials, select VERIFY CONNECTIVITY. A green checkmark indicates a successful connection. If verification fails, check your credentials and permissions.

Optional configurations

• To change the repositories OX scans and monitors, see the section Change the repositories OX scans.

• To connect more Bitbucket accounts to the same organization in the OX platform, see the section Connect multiple Bitbucket accounts.

Connect with user name and token

Step 1: Open the Bitbucket connector [OX]

1. Verify that the prerequisites are in place.

2. In OX, go to Connectors and select Bitbucket Cloud > USER NAME & TOKEN.

   
3. Select HELP CONNECTING A TOKEN. This opens a screen listing scopes and links to documentation.

   
4. Scroll to see the required scopes and Bitbucket documentation on API tokens.

5. Leave the OX Connector screen open.

Step 2: Create API token with scopes [Bitbucket]

1. In Bitbucket, go to Profiles > Security and select Create API token with scopes.

2. In the next screen:

   • Enter a name for the API token

   • Set the expiry date. OX recommends 365 days.

3. Select Next.

4. In Select app, select Bitbucket, then select Next.

5. In Select scopes, find each scope in turn and enable it in the UI.

   • read:account

   • read:workspace:bitbucket

   • read:project:bitbucket

   • admin:project:bitbucket

   • read:repository:bitbucket

   • write:repository:bitbucket

   • admin:repository:bitbucket

   • read:pullrequest:bitbucket

   • write:pullrequest:bitbucket

   • read:issue:bitbucket

   • write:issue:bitbucket

   • read:snippet:bitbucket

   • read:webhook:bitbucket

   • write:webhook:bitbucket

   • read:pipeline:bitbucket

   • read:runner:bitbucket

   • read:user:bitbucket

6. In the Create token dialog, review the scopes and select Create token.

7. In the next screen, copy the token and store it securely. You cannot view it again. Best practice: Store credentials in a secrets manager and set a reminder to rotate it according to your policy.

8. Select Close.

Step 3: Complete the connection [OX]

1. Go to Connectors and select Bitbucket Cloud > BITBUCKET APP > USER NAME & TOKEN.

   
2. Enter the following parameters.

Parameter	Details
Bitbucket Cloud Host URL	https://api.bitbucket.org/2.0 (system-generated
User Name	Your Bitbucket email
API Token	Your Bitbucket token
Connection Name	Enter a meaningful name

1. Select CONNECT. OX validates the credentials.

2. In Configure your Bitbucket connector, select the repos you want OX to scan.

   
3. Select SAVE. A success message shows briefly at the bottom of the screen.

4. In Configure your Bitbucket credentials, select VERIFY CONNECTIVITY. A green checkmark indicates a successful connection. If verification fails, check your credentials and permissions.

Optional configurations

• To change the repositories OX scans and monitors, see the section Change the repositories OX scans.

• To connect more Bitbucket accounts to the same organization in the OX platform, see the section Connect multiple Bitbucket accounts.

Change the repositories OX scans

Once you have a connection, you can change the repositories that OX scans and monitors.

1. Use the Gear icon at the bottom of the Configuration screen.

2. The locations or objects OX scans and monitors display.

3. Change the selection as needed.

4. Select SAVE.

Connect multiple Bitbucket accounts

You can connect multiple Bitbucket Cloud accounts within the same OX organization. OX secures all accounts under a single organization, and each account can use a different connection method.

This setup is useful for large organizations where different teams manage separate Bitbucket Cloud workspaces or require different authentication models. You can combine connection methods—for example:

• Use the Bitbucket app for streamlined setup and app-level access.

• Use user name and password/token for accounts that do not support app installation.

• Use an identity provider for centrally managed user access.

To add another Bitbucket account, select the connection method and follow the steps in this article.