# 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.

<mark style="color:red;">missing active issues image</mark>

## 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.

<table><thead><tr><th width="255.2222900390625">Bitbucket Cloud</th><th>OX Security</th></tr></thead><tbody><tr><td>Pipelines</td><td>CI/CD Pipelines</td></tr><tr><td>Repositories</td><td>Applications</td></tr></tbody></table>

## Connection methods

For general information about connection methods, see the article [Connection methods](/get-started/onboarding-to-ox/source-control/connection-methods.md).

There are three options to connect Bitbucket Cloud to OX.

<table><thead><tr><th width="211.3406982421875" valign="top">Connection Method</th><th valign="top">Details</th></tr></thead><tbody><tr><td valign="top"><a href="#connect-with-the-ox-bitbucket-app">Bitbucket App </a>(recommended)</td><td valign="top">Use the OX-created application for streamlined connection with app-level permissions. Simplifies installation and authorization.</td></tr><tr><td valign="top"><a href="#connect-with-identity-provider">Identity Provider</a></td><td valign="top">Use your existing connection for centralized authentication.</td></tr><tr><td valign="top"><a href="#connect-with-username-and-token">User name and token</a></td><td valign="top">This method replaced connecting with a user name and password.</td></tr></tbody></table>

## Prerequisites

#### Prerequisites for all connection methods

<table><thead><tr><th width="227.333251953125">Prerequisite</th><th>Description</th></tr></thead><tbody><tr><td>OX permissions</td><td>Permission to configure connectors</td></tr><tr><td>Bitbucket Cloud access</td><td>Access to the Bitbucket Cloud workspace(s) you want to connect</td></tr></tbody></table>

#### Additional prerequisites by connection method

<table><thead><tr><th width="244.851806640625" valign="top">Connection Method</th><th valign="top">Prerequisites</th></tr></thead><tbody><tr><td valign="top">Bitbucket app</td><td valign="top">Permission to install apps in the workspace</td></tr><tr><td valign="top">Identity Provider (IdP)</td><td valign="top">Access to Bitbucket Cloud using an OAuth connection and Bitbucket Cloud administrator access</td></tr><tr><td valign="top">User name and token</td><td valign="top">Bitbucket account with permission to generate tokens</td></tr></tbody></table>

## 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](#prerequisites) are in place.
2. In OX, go to **Connectors** and select **Bitbucket Cloud > BITBUCKET APP**.<br>

   <div align="left"><figure><img src="/files/6QIosZ6VwXPSYJXqEsYW" alt=""><figcaption></figcaption></figure></div>
3. Select **CONNECT**. OX validates the credentials.
4. The **Grant access** dialog opens.<br>

   <div align="left"><figure><img src="/files/AifV7cnymemedOIb0JBI" alt="" width="377"><figcaption></figcaption></figure></div>
5. In **Configure your Bitbucket Cloud connector**, select the repos you want OX to scan.<br>

   <div align="left"><figure><img src="/files/3FOXAVo3jPaTPamQxhLd" alt="" width="327"><figcaption></figcaption></figure></div>
6. Select **SAVE**.
7. In **Configure your Bitbucket Cloud credentials**, select **VERIFY CONNECTIVITY.**<br>

   <div align="left"><figure><img src="/files/LjFO9vgJTcSMiVEp1qtz" alt="" width="563"><figcaption></figcaption></figure></div>

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](#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-multiple-bitbucket-accounts).

## Connect with Identity Provider

1. Verify that the [prerequisites](#prerequisites) are in place.
2. In OX, go to **Connectors** and select **Bitbucket Cloud > IDENTITY PROVIDER**.<br>

   <div align="left"><figure><img src="/files/bTpc02SuWPVuNkZeaQQQ" alt="" width="563"><figcaption></figcaption></figure></div>
3. Select **CONNECT**. OX validates the credentials.
4. In **Confirm access to your account**, select **Grant access**.<br>

   <div align="left"><figure><img src="/files/SLky1OA2UDoIjZf6maOL" alt="" width="447"><figcaption></figcaption></figure></div>
5. In **Configure your Bitbucket connector**, select the repos you want OX to scan.<br>

   <div align="left"><figure><img src="/files/jmqeSkKtr8vXvJ0rOdND" alt="" width="327"><figcaption></figcaption></figure></div>
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](#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-multiple-bitbucket-accounts).

## Connect with user name and token

**Step 1: Open the Bitbucket connector \[OX]**

1. Verify that the [prerequisites](#prerequisites) are in place.
2. In OX, go to **Connectors** and select **Bitbucket Cloud > USER NAME & TOKEN**.<br>

   <div align="left"><figure><img src="/files/5t4uMwcnKlC9R9P6hHOb" alt="" width="543"><figcaption></figcaption></figure></div>
3. Select **HELP CONNECTING A TOKEN**. This opens a screen listing scopes and links to documentation.<br>

   <div align="left"><figure><img src="/files/x1HhgMQ9bPaQw8nD7Hsp" alt="" width="375"><figcaption></figcaption></figure></div>
4. Scroll to see the required scopes and Bitbucket documentation on [API tokens](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/).
5. Leave the OX Connector screen open.<br>

**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**.<br>

   <div align="left"><figure><img src="/files/ZWeBReVCPXKSknOEnXfA" alt="" width="543"><figcaption></figcaption></figure></div>
2. Enter the following parameters.

<table><thead><tr><th width="235.3408203125" valign="top">Parameter</th><th width="396.392578125" valign="top">Details</th></tr></thead><tbody><tr><td valign="top">Bitbucket Cloud Host URL</td><td valign="top">https://api.bitbucket.org/2.0 (system-generated</td></tr><tr><td valign="top">User Name</td><td valign="top">Your Bitbucket email</td></tr><tr><td valign="top">API Token</td><td valign="top">Your Bitbucket token</td></tr><tr><td valign="top">Connection Name</td><td valign="top">Enter a meaningful name</td></tr></tbody></table>

3. Select **CONNECT**. OX validates the credentials.
4. In **Configure your Bitbucket connector,** select the repos you want OX to scan.<br>

   <div align="left"><figure><img src="/files/XCmOF3cfwZtguMft7DPB" alt="" width="327"><figcaption></figcaption></figure></div>
5. Select **SAVE**. A success message shows briefly at the bottom of the screen.
6. 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](#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-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**.

<div align="left"><figure><img src="/files/ZERRqHcNkBhvA0kzSvuz" alt="" width="375"><figcaption></figcaption></figure></div>

## 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.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ox.security/get-started/onboarding-to-ox/source-control/bitbucket-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.