Last updated Jul 17, 2024

Integrate Compass with Bitbucket Cloud

What is Bitbucket Cloud?

Bitbucket Cloud is a Git-based code hosting and collaboration tool, built for teams.

Compass currently supports Bitbucket Cloud as a tool to:

  • import components from Bitbucket repositories to track them in Compass
  • automate component management from an external tool with config-as-code
  • sync component data, such as deployment activity, from Bitbucket to Compass
  • automatically scan Bitbucket for API documentation and endpoints, which display on relevant component pages

We’ll show you how to integrate Compass with Bitbucket by installing and configuring the Bitbucket Cloud app in Compass.

Integrate Compass with Bitbucket Cloud

To integrate Compass with Bitbucket Cloud, you must first install the Bitbucket app in Compass. Then, you connect Compass to your Bitbucket workspace that contains the repositories from where you want to manage the component.

When you integrate an app with Compass, other Compass users can view events and metrics data sent from the app to Compass, even if they don't have access to that data in the underlying app. For example, when you integrate Bitbucket with Compass, someone who doesn't have access to a repository can see the events and metrics related to that repository in Compass. The same applies to data sent from this app to Compass.

Before you begin

Ensure that you are an admin on:

  • the Bitbucket workspace(s) that you want to connect with Compass
  • your Compass instance

Perform the integration

To integrate Compass with Bitbucket Cloud:

  1. In Compass, select Apps from the top navigation bar.
  2. On the Bitbucket tile, select Install. The Bitbucket app installs.
  3. On the Bitbucket tile, select Configure.
  4. If not already done, authorize the Bitbucket app to access Compass on your behalf. Select Allow access and follow the on-screen instructions.
    • This step appears only once on your Compass instance for each app you install. So, if you've already authorized the Bitbucket app before, proceed to the next step.
  5. Select Connect to Bitbucket.
  6. The Authorize for workspace list displays the workspaces that you are an admin of. Select a workspace to connect with Compass.
  7. Select Grant Access.

Now you can manage components from repositories within the connected Bitbucket workspace(s) by setting up configuration as code (config-as-code) for your components. Learn how to manage components via config-as-code

Connect Bitbucket as an event source to components

The Bitbucket app for Compass collects events to display on the Compass activity feed and automatically calculate certain metrics for your components. The following events are collected when you connect a Bitbucket repository to your component:

EventHow
DeploymentBitbucket Pipelines deployments for Production and Staging category environments only

To connect a repository to your component after performing the Bitbucket integration steps above:

  1. Go to your component in Compass.
  2. Search for your repository in the Repositories link section of the component, or paste a URL to your Bitbucket repository. Learn more about adding links to a component's resources

Events will begin to appear on the activity feed and metrics will begin to calculate on the component details page.

Take a note of these additional points:

  • A component's deployment activity appears in Compass only if you've connected the event source to the component and if the component has at least one deployment.
  • The activity feed also shows deployment events from a component's upstream dependencies if you've connected event sources to those components. The deployment events from your component’s dependencies appear alongside the deployment events from your component.
  • You can add links to any repositories from the Bitbucket workspace(s) connected to your Compass site. The activity feed shows deployment events from all those repositories when you set up and configure Bitbucket Pipelines. The activity feed does not show deployment events from any repositories that are not in the connected Bitbucket workspace(s).
  • Suppose you integrate Compass with Bitbucket Cloud after adding a repository link to the component’s details page. In that case, the activity feed gets the deployment events from the connected repository once your app integration completes. The activity feed also backfills historical deployment events from the connected repository.

Set up and configure Bitbucket Pipelines for activity feed

Bitbucket Pipelines is an integrated CI/CD service built into Bitbucket that allows you to automatically build, test, and deploy your code based on a configuration file in your repository. Setting up and configuring a pipeline enables you to view a component’s deployment activity in Compass.

To set up and configure a pipeline for activity feed:

  1. Set up a pipeline in your component’s repository.
  2. Set up and configure production or staging-type deployment environments. Learn more about setting up deployments in Bitbucket
    • In this example, we've set up two production-type environments named production and prod-east. Production environments in Bitbucket
  3. Configure the deployment steps in the bitbucket-pipelines.yml file. Add the deployment keyword, followed by the environment's name.
    • These steps in our pipeline generate deployment events from the two production-type environments:
      1
      2
      - step:
          name: 'Deploy to production'
          deployment: production
          trigger: 'manual'
          script:
            - echo "Deployed to production."
      - step:
          name: 'Deploy to prod-east'
          deployment: prod-east
          trigger: 'manual'
          script:
            - echo "Deployed to prod-east."
      

Disconnect the Bitbucket workspace connected with Compass

Compass’s integration with a Bitbucket workspace lets you manage your components with configuration as code (config-as-code) by using Bitbucket as a component management tool. However, if you want to configure a different workspace or no longer want to use config-as-code, you can disconnect your current Bitbucket workspace from Compass.

We'll show you how to disconnect a Bitbucket workspace from Compass.

Before you begin

Ensure that you are an admin on:

  • the Bitbucket workspace that is connected with Compass
  • your Compass instance

Once you disconnect a Bitbucket workspace, any managed components in Compass are disconnected and will no longer be synced with Bitbucket. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.

Disconnect the workspace(s)

To disconnect a Bitbucket workspace from Compass:

  1. In Compass, from the top navigation bar, select Apps.
  2. On the Bitbucket tile, select Disconnect workspace.
  3. On the Disconnect workspace dialog, select Go to Bitbucket app management. We’ll take you to the Bitbucket workspace settings in Bitbucket.
  4. On the Manage installed apps screen, from the categories list, select All categories.
  5. Select Compass app, then Remove and confirm your action. The Compass app disconnects from Bitbucket.
  6. Verify that the Bitbucket workspace you just disconnected is no longer connected with Compass. If you have a multiple workspaces connected, the page should still display the other connected workspaces.

Now you can manage the components previously managed via config-as-code from multiple workspaces through the Compass UI. You can also configure multiple workspaces at once. Learn how to integrate Compass with Bitbucket Cloud and configure a workspace.

Uninstall the Bitbucket Cloud app from Compass

If you no longer wish to use Bitbucket as a component management tool, you can uninstall the Bitbucket app from Compass.

We'll show you how to uninstall the Bitbucket Cloud app.

Before you begin

Once you uninstall the Bitbucket Cloud app, any managed components in Compass are disconnected and will no longer be synced with Bitbucket. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.

Uninstall the Bitbucket Cloud app

To uninstall the Bitbucket workspace from Compass:

  1. In Compass, from the top navigation bar, select Apps.
  2. Disconnect the Bitbucket workspace connected with Compass, if you’ve not already done so.
  3. On the Bitbucket tile, select Uninstall. The Bitbucket Cloud app uninstalls from Compass.

Now you can manage components from multiple workspaces via the Compass UI. At any time, you can again integrate Compass with Bitbucket Cloud to set up config-as-code for component management.

Supported metrics

Learn more about working with metrics in Compass.

The Bitbucket app for Compass supports the following metrics:

MetricDescriptionHow it's calculated
Build Success RateThe ratio of build events for this component that were successful compared to all build events (including failed, timed out, etc.). Only the last 25 build events are evaluated.Build events on the default branch.
Build TimeThe average amount of time it took for a build event to finish over the last ten successful build events.Build events on the default branch.
Deployment FrequencyThe weekly average of times a deployment event to production occurred in the previous four weeks.Deployment events from Bitbucket Pipelines.
Deployment TimeThe average amount of time it took for a deployment in the production environment to complete over the last 25 deployments.Deployment events from Bitbucket Pipelines.
Open Pull RequestsThe count of currently open pull requests for a component.Pull requests for the default branch currently in the open state.
PR Cycle TimeHow long it took on average for a Pull Request to go from ‘open’ to ‘merged’ over the last ten pull requests.Pull request open and close events for the default branch.

Import components from Bitbucket

Once you have finished setting up the integration, you can import your repositories from Bitbucket into Compass as components. Simply select Create from the top navigation bar in Compass and then choose "Import components" to get started. Learn more about importing from Bitbucket here.

Automatic import

By default, the Bitbucket app for Compass will detect when repositories are created in any connected Bitbucket workspace and automatically create components in Compass for them. The best way to keep your Compass catalog accurate and up-to-date is using automation to make sure all your components are there.

All components created this way will be of type service but you can change that. Compass also knows when you're using a template and takes care not to create duplicate components.

If you want to disable the automatic import feature for any connected workspace:

  1. Select Manage your apps from the Apps navigation menu in Compass.
  2. Select Configure on the Bitbucket app card.
  3. Toggle Automatic import to off for each connected Bitbucket workspace. Repositories will now need to be manually imported.

Config as code

Optionally, Compass can open a pull request to add a compass.yml file enabling config as code to any components imported with automatic import. Learn more about config as code.

To enable config as code for any automatically imported components:

  1. Select Manage your apps from the Apps navigation menu in Compass.
  2. Select Configure on the Bitbucket app card.
  3. Toggle Automatic import on for each connected Bitbucket workspace you want to manage with config as code (if not already on).
  4. Toggle Config as code on for each connected Bitbucket workspace you want to manage with config as code.

Rate this page: