Skip to main content

Bitbucket

CatalogGitOpsScorecards

Overview​

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.

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

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

How to configure Bitbucket with Cortex​

Step 1: Start the configuration in Cortex​

  1. In Cortex, navigate to the Bitbucket settings page:
    1. In Cortex, click your avatar in the lower left corner, then click Settings.
    2. Under "Integrations", click Bitbucket.
  2. Click Add Bitbucket configuration.
    • In the modal that appears, the configuration differs depending on the method you choose. See the next steps for instructions on each method.

Step 2: Choose a configuration method​

In the configuration modal, you can authenticate your integration via the following options:

  • Cloud: Using the Cortex Atlassian app or using an app password
  • On-prem: Using Basic auth or using OAuth

See the tabs below for instructions on the method you choose.

caution

If you do not see the settings page you're looking for, you may not have permission to access that page. Please contact your admin for assistance.

Step 1: Install the Cortex Atlassian app​

Follow the installation instructions in the Atlassian Marketplace for the Cortex app.

Step 2: Finish the configuration in Cortex​

  1. In the upper right corner of the "Add Bitbucket configuration" modal, select Atlassian app. Choose an integration method for Bitbucket
  2. 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.
  3. 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 in Cortex, click Atlassian Application. Click on Atlassian Application
  2. In the popup that appears, click Grant access to authorize Cortex access to your Atlassian Workspace.

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.

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. Configure a webhook secret

How to connect Cortex entities to 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: <workspace>/<repo>
    basepath: myService # optional
    alias: myApp # optional
FieldDescriptionRequired
repositoryorg/repo as defined in Bitbuckettrue
basepathIf the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdirectoryfalse
aliasAlias is optional and only relevant if you have opted into multi account supportfalse

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.
FieldDescriptionRequired
typeOwnership type; must be defined as group for Bitbucket teams✓
nameBitbucket team name✓
providerName of integration (in this case, BITBUCKET)✓
descriptionDescription 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.

Expected results​

Entity pages​

The Bitbucket integration will populate 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.

Integrations - Git​

You can access more detailed information pulled from Bitbucket in the Git tab under Integrations in the sidebar. At the top of the Git 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.

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.

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

Details

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​

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 are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

  • Email: help@cortex.io, 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.