# Bitbucket
{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}
[Bitbucket](https://bitbucket.org/product/) is a Git-based version control system from Atlassian. You can use Bitbucket to drive insights into repository details in the Catalog and Scorecard rules.
Integrating Bitbucket with Cortex allows you to:
* Discover and track ownership of Bitbucket entities
* [View Bitbucket data on entity pages](#view-bitbucket-information-on-entity-pages-in-cortex) in Cortex
* Follow a [GitOps](/configure/gitops.md) workflow with Bitbucket
* View information about pull requests in the [engineering homepage](#engineering-homepage)
* Use Bitbucket metrics in [Eng Intelligence](#eng-intelligence) to understand key metrics and gain insight into services, incident response, and more
* Create [Scorecards](#scorecards-and-cql) that track progress and drive alignment on projects involving your Bitbucket repositories
{% hint style="info" %}
Bitbucket data in [Eng Intelligence](#eng-intelligence) and in the [engineering homepage](#dev-homepage) is available in private beta. Please contact your Cortex Customer Success Manager for access.
{% endhint %}
## How to configure Bitbucket with Cortex
There are multiple options for integrating with Bitbucket:
* Cloud: Using a workspace token (recommended), the Cortex Atlassian app, or an app password.
* On-prem: Using Basic auth or using OAuth
* You can also integrate using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises Bitbucket data.
See the tabs below for instructions on the method you choose.
{% tabs %}
{% tab title="Workspace token" %}
**Configure Cortex with Bitbucket using a workspace token**
**Step 1: Generate a workspace token in Bitbucket**
1. In Bitbucket, navigate to **Settings > Workspace settings > Access tokens**.
2. Create a workspace-level access token. Include the following scopes:
1. `Repositories: Read`
2. `Pull requests: Read`
**Step 2: Configure the integration in Cortex**
1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
* Click **Integrations** from the main nav. Search for and select **Bitbucket**.
2. For the configuration type, select **Cloud (workspace token)**.\
3. Configure the form:
* **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
* **Token**: Enter the workspace token you generated in Bitbucket.
4. Click **Save**.
**Step 3: Set your Bitbucket workspace**
1. On the [Bitbucket Settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, next to your integration's alias, click **Add workspace**.\
2. In the "Workspace configuration" modal, enter your Workspace name.
* You can find this in Bitbucket under **Settings > Workspace settings**.
3. Click **Save**.
{% endtab %}
{% tab title="Atlassian app" %}
**Configure Cortex with Bitbucket using the Atlassian app**
**Step 1: Install the Cortex Atlassian app**
Follow the [installation instructions in the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1225295/cortex?tab=installation\&hosting=cloud) for the Cortex app.
**Step 2: Configure the integration in Cortex**
1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
* Click **Integrations** from the main nav. Search for and select **Bitbucket**.
2. Click **Add Bitbucket configuration**.
3. For the configuration type, select select **Atlassian app**.
4. Configure the "Add Bitbucket configuration" form:
* **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
5. Click **Save**.
* You will be redirected to the Bitbucket Settings page in Cortex.
**Step 3: Connect to Atlassian from Cortex**
1. On the [Bitbucket settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, click **Atlassian Application**. 
2. In the popup that appears, click **Grant access** to authorize Cortex access to your Atlassian Workspace.
{% endtab %}
{% tab title="App password" %}
**Configure Cortex with Bitbucket using an app password**
{% hint style="warning" %}
Bitbucket is [deprecating app passwords on June 9, 2026](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). If you are currently using an app password, we recommend switching to a workspace token or the Atlassian app before that date.
{% endhint %}
**Step 1: Create an app password**
* Follow Atlassian's documentation to [create an app password for Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).
* Make sure to give the app password the following minimum permissions: `Repositories: Admin`, `Repositories: Read`, `Pull requests: Read`
**Step 2: Configure the integration in Cortex**
1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
* Click **Integrations** from the main nav. Search for and select **Bitbucket**.
2. Click **Add configuration**.
3. For the configuration type, select **Cloud (basic auth)**.
4. Configure the "Add Bitbucket configuration" form:
* **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
* **Username**: Enter your Bitbucket username.
* You can find this in Bitbucket under **Personal settings > Account settings > Bitbucket profile settings**.
* **Password**: Enter the app password you created in the previous steps.
5. Click **Save**.
* You will be redirected to the Bitbucket Settings page.
**Step 3: Set your Bitbucket workspace**
1. On the [Bitbucket Settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, next to your integration's alias, click **Add workspace**.\
2. In the "Workspace configuration" modal, enter your Workspace name.
* You can find this in Bitbucket under **Settings > Workspace settings**.
3. Click **Save**.
{% endtab %}
{% tab title="Basic" %}
**Configure Cortex with Bitbucket using a on-premises basic auth**
{% hint style="warning" %}
Bitbucket is [deprecating app passwords on June 9, 2026](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). If you are currently using an app password for basic auth, we recommend switching to an alternative authentication method before that date.
{% endhint %}
**Step 1: Create an app password**
* Follow Atlassian's documentation to [create an app password for Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).
* Make sure to give the app password the following minimum permissions: `Repositories: Admin`, `Repositories: Read`, `Pull requests: Read`
**Step 2: Configure the integration in Cortex**
1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
* Click **Integrations** from the main nav. Search for and select **Bitbucket**.
2. Click **Add configuration**.
3. For the configuration type, select **On-prem (basic auth)**.
4. Configure the "Add Bitbucket configuration" form:
* **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
* **Host**: Enter your Bitbucket on-prem host, e.g., `https://bitbucket.example.com`.
* **Username**: Enter your Bitbucket username.
* You can find this in Bitbucket under **Personal settings > Account settings > Bitbucket profile settings**.
* **Password**: Enter the app password you created in the previous steps.
5. Click **Save**.
Note: When using an on-premises configuration of Bitbucket, the language does not populate on [entity detail pages](#view-bitbucket-information-on-entity-pages-in-cortex).
{% endtab %}
{% tab title="OAuth" %}
**Configure Cortex with Bitbucket on-premises using OAuth**
{% hint style="info" %}
Scaffolder and Workflow automation are supported with this configuration. See [Registering a Scaffolder template](/streamline/workflows/scaffolder.md) for setup details.
{% endhint %}
**Prerequisites**
To configure this integration with on-prem OAuth, you must be running a self-hosted Bitbucket instance with Bitbucket Server or Data Center version 7.20 or higher.
**Step 1: Set up an application link in Bitbucket**
1. In your Bitbucket server, navigate to **Settings > System > Application Links > Create Link**.
2. Configure the application link:
* For the application type, select "External Application."
* For the direction, select "Incoming."
* For the redirect URL:
* Default configuration: Enter the URL of your Cortex instance and `/oauth/internal/bitbucket`.
* Non-default configuration: Enter the URL of your Cortex instance and `/oauth/internal/bitbucket/{alias}`.
* For the Permission, select `Projects: Admin` and `Repositories: Admin`.
3. Click **Save**.
4. Copy the client ID and client secret. You will need these in the next steps.
**Step 2: Configure the integration in Cortex**
1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
* Click **Integrations** from the main nav. Search for and select **Bitbucket**.
2. Click **Add configuration**.
3. For the configuration type, select **On-prem (OAuth)**.
4. Configure the "Add Bitbucket configuration" form:
* **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
* **Host**: Enter your Bitbucket on-prem host, e.g., `https://bitbucket.example.com`.
* **Client ID**: Enter the client ID you obtained in the previous steps.
* **Client secret**: Enter the client secret you obtained in the previous steps.
5. Click **Save**.
Note: When using an on-premises configuration of Bitbucket, the language does not populate on [entity detail pages](#view-bitbucket-information-on-entity-pages-in-cortex).
{% endtab %}
{% tab title="Relay" %}
**Configure Bitbucket with Cortex Axon Relay**
{% hint style="info" %}
Scaffolder and Workflow automation are supported when connecting Bitbucket via Axon Relay. See [Registering a Scaffolder template](https://docs.cortex.io/streamline/workflows/scaffolder) for setup details.
{% endhint %}
See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay.md) for instructions. Make sure to follow the Bitbucket-specific instructions for the docker-compose.yml file.
{% endtab %}
{% endtabs %}
Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in Settings.
You can also use the **Test all configurations** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
**Configure the integration for multiple Bitbucket accounts**[****](https://docs.cortex.io/docs/reference/integrations/bitbucket#configure-the-integration-for-multiple-propsintegration-accounts)
The Bitbucket integration has multi-account support. You can add a configuration for each additional by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Bitbucket page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of Bitbucket. See the [Identity mapping](/configure/settings/managing-users/identity-mapping.md) documentation for more information.
### Limit which Bitbucket projects are used for the integration
If you are a part of multiple projects in Bitbucket but you only want to show repositories for a specific set of projects, you can specify the projects in Cortex:
1. Navigate to the [Bitbucket integration settings page](https://app.getcortexapp.com/admin/settings/bitbucket).
2. Click the pencil icon in the row containing the Bitbucket configuration you want to edit.\\
3. Under **Project names**, select which projects you want to include.\
4. At the bottom of the side panel, click **Save**.
### Use webhooks for GitOps functionality
To use webhooks for GitOps functionality, you need to set a secret token on the [Bitbucket Settings](https://app.getcortexapp.com/admin/settings/bitbucket) page. This helps Cortex identify that the webhook event is valid. Make sure to enter the same secret when configuring the webhook on Bitbucket Server. \\
## How to connect Cortex entities to Bitbucket
### Import entities from Bitbucket
See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services.md#creating-services) for instructions on importing entities.
### Editing the entity descriptor
**Set repository details**
By specifying the `x-cortex-git` field in your Cortex entity descriptor, you'll be able to see Git information in the entity page, including the top language, recent commits, and top contributors.
```yaml
x-cortex-git:
bitbucket:
repository: /
basepath: myService # optional
alias: myApp # optional
```
| Field | Description | Required |
| ------------ | -------------------------------------------------------------------------------------------------- | -------- |
| `repository` | `org/repo` as defined in Bitbucket | true |
| `basepath` | If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdirectory | false |
| `alias` | Alias is optional and only relevant if you have opted into multi account support | false |
The value for `repository` should be the *workspace/repo* as defined in Bitbucket.
**Ownership**
You can define the following block in your Cortex entity descriptor to add your Bitbucket teams.
```yaml
x-cortex-owners:
- type: group
name: Team Name
provider: BITBUCKET
description: This is a description for this Bitbucket team that owns this entity.
```
| Field | Description | Required |
| ------------- | -------------------------------------------------------------- | :------: |
| `type` | Ownership type; must be defined as `group` for Bitbucket teams | **✓** |
| `name` | Bitbucket team name | **✓** |
| `provider` | Name of integration (in this case, `BITBUCKET`) | **✓** |
| `description` | Description for the Bitbucket team | |
### Identity mappings
Cortex maps users' email addresses to discovered Bitbucket accounts, so you never need to define email ownership in an entity descriptor.
You can confirm users' Bitbucket accounts are connected from [Bitbucket identity mappings in settings](/configure/settings/managing-users/identity-mapping.md).
## Using the Bitbucket integration
### View Bitbucket information on entity pages in Cortex
The Bitbucket integration populates the **Repository** block on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md). For cloud configurations, it also populates the **Language** block. If a Bitbucket team has been defined as the owner for an entity, it will also appear in the Owners block.
In the **Recent activity** preview, you'll find the recent commits and releases.
#### **Events**
On an entity's **Events** page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Bitbucket and includes a timestamp.
#### **CI/CD**
To see pipeline runs for Bitbucket, use the [deploys API](/ingesting-data-into-cortex/entities-overview/entities/deploys.md) to add deploy information. After doing this, from the **CI/CD > Deploys** page in the entity's sidebar, you will see a history of pipeline runs.
#### **Workflows**
If a Workflow applies to a given entity, any actions you can perform are available under the **Workflows** link in the side panel of an entity.
#### **Repository**
You can access more detailed information pulled from Bitbucket in the **Repository** link in the sidebar. At the top of the repository page, see the repositories associated with that entity. For cloud configurations, you can also see the most-used language in files for that entity. In the **Top contributors** block, you'll find the three users who have contributed the most code and the number of their contributions.
In the **Commits** section, you'll find the 10 most recent commits and metadata about each. Below **Commits** is the **Recent releases** section, which includes the 5 most recent releases.
#### **Packages**
Packages are automatically scraped from your Git repos or they can be submitted via the [packages API](/api/readme/packages.md). The package file must be in the root of your repository — or, if you're using `basepath`, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) using `packages()`.
To view packages, click **Packages** in the entity's sidebar.
The following package types are automatically scraped from repositories:
* JavaScript / Node.js: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Python: `requirements.txt`, `pipfile.lock`
* .NET (C#): `packages.lock.json`
* Java: `pom.xml`
* Go: `go.sum`
All other files of these types can be added via the [packages API](/api/readme/packages.md).
### Engineering homepage
{% hint style="info" %}
Bitbucket in the homepage is available in private beta. Please contact your Cortex Customer Success Manager for access.
Note: Because of rate limits, Bitbucket ingestion in the homepage is limited to repositories that are mapped to an entity in Cortex.
{% endhint %}
The Bitbucket integration enables Cortex to pull information about pull requests and work items into the [homepage](/streamline/homepage.md). You can find your open pull requests and any pull requests assigned to you for review.
Pull requests from Bitbucket are refreshed every 5 minutes.
### Eng Intelligence
{% hint style="info" %}
Bitbucket in Eng Intelligence is available in private beta. Please contact your Cortex Customer Success Manager for access.\
\
Note: Because of rate limits, Bitbucket ingestion in Eng Intelligence is limited to repositories that are mapped to an entity in Cortex.
{% endhint %}
The [Eng Intelligence tool](/improve/eng-intelligence.md) also uses pull request data from Bitbucket to generate metrics:
* Average PR open to close time
* Avg time to first review
* Avg time to approval
* PRs opened
* Weekly PRs merged
* Avg PRs reviewed/week
You can read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence walkthrough.
### Scorecards and CQL
With the Bitbucket integration, you can create Scorecard rules and write CQL queries based on Bitbucket details.
See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.
Approvals required to merge
The total number of approvals required to merge a Pull Request into the repository, defaulting to 0 if no approvals are defined.
**Definition:** `git.numOfRequiredApprovals(): Number`
**Example**
In a Scorecard, you can write a rule to encourage at least one approval for each Pull Request:
```
git.numOfRequiredApprovals() >= 1
```
Git repository set
Check if an entity has a registered Git repository.
**Definition:** `git (==/!=) null: Boolean`
**Example**
In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
```
git != null
```
Pipeline build success rate
The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed). **Definition:** `git.percentBuildSuccess(): Number`
**Example**
In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:
```
git.percentBuildSuccess() > 0.9
```
### View integration logs
{% hint style="info" %}
This feature is available in Cortex cloud.
{% endhint %}
While viewing an integration's settings page, click the **Logs** tab to view error logs from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
Click into a row to get more information, including time stamp, status code, full error, and request path.
## Background sync
Cortex conducts a background sync of Bitbucket identities every day at 10 a.m. UTC. Repositories are refreshed every day at 2 p.m. UTC.
## Troubleshooting and FAQ
**Rules are failing saying that I don't have file `x`, but I verified that the file exists.**
We always use the default branch for file existence checks. Make sure that the file is present in the default branch.
## Still need help?[](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help)
The following options are available to get assistance from the Cortex Customer Engineering team:
* **Email**: , or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
---
# 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.cortex.io/ingesting-data-into-cortex/integrations/bitbucket.md?ask=
```
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.