LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Overview
  • How to configure Bitbucket with Cortex
  • Use webhooks for GitOps functionality
  • How to connect Cortex entities to Bitbucket
  • Import entities from Bitbucket
  • Editing the entity descriptor
  • Identity mappings
  • Expected results
  • Entity pages
  • Engineering homepage
  • Eng Intelligence
  • Scorecards and CQL
  • Background sync
  • Troubleshooting and FAQ
  • Still need help?​

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Integrations

Bitbucket

Last updated 5 days ago

Was this helpful?

Overview

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.

The Bitbucket integration can also be used to power Cortex with .

After configuring this integration, you will see the related Bitbucket repo listed on an entity's details page, linking to the repository in Bitbucket:

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

  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, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations", click Bitbucket.

  1. Click Add Bitbucket configuration.

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

  3. Click Save.

Step 3: Set your Bitbucket workspace

  1. In the "Workspace configuration" modal, enter your Workspace name.

    • You can find this in Bitbucket under Settings > Workspace settings.

  2. Click Save.

Configure Cortex with Bitbucket using the Atlassian app

Step 1: Install the Cortex Atlassian app

Step 2: Configure the integration in Cortex

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations", click Bitbucket.

  1. Click Add Bitbucket configuration.

  2. For the configuration type, select select Atlassian app.

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

  4. Click Save.

    • You will be redirected to the Bitbucket Settings page in Cortex.

Step 3: Connect to Atlassian from Cortex

  1. In the popup that appears, click Grant access to authorize Cortex access to your Atlassian Workspace.

Configure Cortex with Bitbucket using an app password

Step 1: 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, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations", click Bitbucket.

  1. Click Add configuration.

  2. For the configuration type, select Cloud (basic auth).

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

  4. Click Save.

    • You will be redirected to the Bitbucket Settings page.

Step 3: Set your Bitbucket workspace

  1. In the "Workspace configuration" modal, enter your Workspace name.

    • You can find this in Bitbucket under Settings > Workspace settings.

  2. Click Save.

Configure Cortex with Bitbucket using a on-premises basic auth

Step 1: 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, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations", click Bitbucket.

  1. Click Add configuration.

  2. For the configuration type, select On-prem (basic auth).

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

  4. Click Save.

Configure Cortex with Bitbucket on-premises using OAuth

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

    • 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, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations", click Bitbucket.

  1. Click Add configuration.

  2. For the configuration type, select On-prem (OAuth).

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

  4. Click Save.

Configure Bitbucket with Cortex Axon Relay

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

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.

Use webhooks for GitOps functionality

How to connect Cortex entities to Bitbucket

Import entities from Bitbucket

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

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.

Expected results

Entity pages

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

Engineering homepage

Bitbucket in the homepage is available in private beta. Please contact your Cortex Customer Success Manager for access.

Pull requests from Bitbucket are refreshed every 5 minutes.

Eng Intelligence

Bitbucket in Eng Intelligence is available in private beta. Please contact your Cortex Customer Success Manager for access.

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

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

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.

The following options are available to get assistance from the Cortex Customer Engineering team:

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

Bitbucket data in and in the is available in private beta. Please contact your Cortex Customer Success Manager for access.

In Cortex, navigate to the .

For the configuration type, select Cloud (workspace token).

On the in Cortex, next to your integration's alias, click Add workspace.

Follow the for the Cortex app.

In Cortex, navigate to the .

On the in Cortex, click Atlassian Application.

Follow Atlassian's documentation to .

In Cortex, navigate to the :

On the in Cortex, next to your integration's alias, click Add workspace.

Follow Atlassian's documentation to .

In Cortex, navigate to the :

In Cortex, navigate to the :

See for instructions.

Configure the integration for multiple Bitbucket accounts

Cortex supports mapping multiple identities for a single user if you have multiple configurations of Bitbucket. See the documentation for more information.

To use webhooks for GitOps functionality, you need to set a secret token on the 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.

See the for instructions on importing entities.

You can confirm users' Bitbucket accounts are connected from .

The Bitbucket integration will populate the Repo and Language detail blocks on an . If a Bitbucket team has been defined as the owner for an entity, it will also appear in the Owners block.

The Bitbucket integration enables Cortex to pull information about pull requests and work items into the . You can find your open pull requests and any pull requests assigned to you for review.

The also uses pull request data from Bitbucket to generate metrics:

See more examples in the in Cortex.

Still need help?

Email: , or open a support ticket in the in app Resource Center

Bitbucket settings page
installation instructions in the Atlassian Marketplace
Bitbucket settings page
create an app password for Bitbucket
Bitbucket settings page
create an app password for Bitbucket
Bitbucket settings page
Bitbucket settings page
Internally hosted integrations
​
Identity mapping
Bitbucket Settings
Bitbucket identity mappings in settings
entity's details page
homepage
Eng Intelligence tool
CQL Explorer
​
help@cortex.io
Eng Intelligence
dev homepage
Bitbucket
GitOps
Bitbucket Settings page
Bitbucket settings page
Bitbucket Settings page
Create services documentation

Packages are automatically scraped from your Git repos or they can be submitted via the . 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 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
CQL explorer
packages API