Bitbucket
Bitbucket 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 in Cortex
Follow a GitOps workflow with Bitbucket
View information about pull requests in the engineering homepage
Use Bitbucket metrics in Eng Intelligence to understand key metrics and gain insight into services, incident response, and more
Create Scorecards that track progress and drive alignment on projects involving your Bitbucket repositories
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.
Configure Cortex with Bitbucket using a workspace token
Step 1: Generate a workspace token in Bitbucket
In Bitbucket, navigate to Settings > Workspace settings > Access tokens.
Create a workspace-level access token. Include the following scopes:
Repositories: Read
Pull requests: Read
Step 2: Configure the integration in Cortex
In Cortex, navigate to the Bitbucket settings page.
In Cortex, click your avatar in the lower left corner, then click Settings.
Under "Integrations", click Bitbucket.
Click Add Bitbucket configuration.
For the configuration type, select Cloud (workspace token).
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.
Click Save.
Step 3: Set your Bitbucket workspace
On the Bitbucket Settings page in Cortex, next to your integration's alias, click Add workspace.
In the "Workspace configuration" modal, enter your Workspace name.
You can find this in Bitbucket under Settings > Workspace settings.
Click Save.
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
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 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:
Navigate to the Bitbucket integration settings page.
Click the pencil icon in the row containing the Bitbucket configuration you want to edit.
Under Project names, select which projects you want to include.
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 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 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.
x-cortex-git:
bitbucket:
repository: /
basepath: myService # optional
alias: myApp # optional
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.
x-cortex-owners:
- type: group
name: Team Name
provider: BITBUCKET
description: This is a description for this Bitbucket team that owns this entity.
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.
Using the Bitbucket integration
View Bitbucket information on entity pages in Cortex
The Bitbucket integration populates the Repo and Language detail blocks on an entity's details page. 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.
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, you'll find the repo(s) associated with that entity and 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. 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 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.
Engineering homepage
The Bitbucket integration enables Cortex to pull information about pull requests and work items into the homepage. 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
The Eng Intelligence tool 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 in Cortex.
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?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
Chat: Available in the 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.
Last updated
Was this helpful?