Written by: Riley Venable

About the Author: Riley Venable is an experienced Atlassian consultant with deep expertise in cloud migration, ITSM, and workflow optimization. With a strong background in helping organizations maximize their use of Atlassian tools, Riley is dedicated to driving efficiency and delivering tailored solutions for clients across various industries. Passionate about the latest developments in the Atlassian ecosystem, Riley shares insights on how teams can leverage technology to achieve their goals.

Atlassian Compass simplifies software component management by integrating Bitbucket repositories and enforcing governance through a centralized platform. This guide will walk you through setting up your environment, enabling smooth component tracking, configuration, and efficient workflow management.

undefined

1. Bulk Import Repositories from Bitbucket

The first step to managing your components in Compass is to import repositories. The Bulk Import feature allows you to import multiple repositories from Bitbucket into Compass simultaneously, saving time and ensuring consistent tracking and governance from the start.

To begin managing your components in Compass, you'll first need to import your repositories:

Use the Import feature to bring in multiple repositories from Bitbucket into Compass simultaneously.
Bulk import saves time by allowing you to manage all relevant repositories at once, ensuring consistent tracking and governance from the start.

undefined

2. Review Pending Components

After the bulk import, your components will be listed in a Pending state. You’ll need to review these components before adding them to your component catalog. Compass automatically identifies new components that have been imported, but they will remain in Pending until reviewed and confirmed.

Review Pending Component: Click on each pending component to review the imported details, such as metadata and configurations. For example, you might see something like:
- Bitbucket for Compass imported Website Backend to your component catalog for you to review.
- Pending components are typically imported from your connected source code management (SCM) apps, such as Bitbucket, GitHub, and GitLab.
Publish Component: Once you've reviewed the component details, you can publish it to add it to your component catalog, making it officially part of your managed inventory.
Delete Permanently: If a component is unnecessary or incorrectly imported, you have the option to delete it permanently from the catalog.

Best Practice: Regularly review all pending components to ensure that only relevant repositories are added to the catalog. This prevents outdated or unnecessary components from cluttering your inventory.

3. Choose Your Management Method

Once your repositories are imported and reviewed, you have two options for managing your components:

Code as Config: For teams that prefer infrastructure-as-code practices, this option allows you to manage component configurations directly through your repositories using YAML files.
User Interface: For those who prefer managing components via an intuitive graphical interface, Compass provides a user-friendly UI for component configuration.

4. Enabling Config as Code

Config as Code allows for powerful, version-controlled component management. Here's how to enable and utilize it:

When you opt for Config as Code, Compass will raise a pull request (PR) for each repository you've imported. This PR contains a compass.yaml file, which holds your component data.
Review and approve the PR, then merge it into the repository. This step links the repository’s configuration to Compass, enabling ongoing synchronization.
The compass.yaml file acts as the single source of truth for your component configuration, making it easier to manage changes and ensuring consistency across your projects.

Best Practice: Keep the compass.yaml file in sync with other infrastructure configuration files in your repository. This approach streamlines the management of all component-related data, such as services, documentation, and ownership.

5. Enabling Automatic Repository Import

To simplify your ongoing workflow, enable the Automatic Import feature in Compass:

Once enabled, Compass will automatically import any new repositories added to your Bitbucket workspace, treating them as components without manual input.
This ensures that your components are always up-to-date in Compass and integrated into your workflow governance framework.

Best Practice: Regularly audit your repositories and imported components to ensure that unnecessary or outdated components aren’t included in your active governance efforts.

Setting Up a Scorecard for Governance

A core feature of Compass is the Scorecard, which allows you to enforce governance policies across your components. By setting up a Scorecard, you can standardize your components, track compliance, and ensure teams are following best practices across the board.

undefined

6. Defining Criteria for Your Scorecard

Scorecards allow you to set up specific criteria for each component, ensuring compliance with organizational standards. Some common criteria include:

Documentation: Ensures proper documentation is linked for each component, which is essential for support, maintenance, and knowledge sharing.
Ownership: Ensures each component has a clearly defined team owner, making accountability clear.
Health Checks: Verifies that the component follows established health criteria, such as service availability, monitoring, and error tracking.

You can define a wide variety of criteria to track component quality and completeness. Scorecards provide a visual overview of how well each component meets the required standards, helping you identify areas needing improvement.

7. Applying Scorecards to Components

You can apply Scorecards to components in two ways:

Manually select components: Choose specific components to evaluate based on your criteria.
Filter by component attributes: Use predefined filters to apply Scorecards to a subset of components based on shared characteristics, such as ownership, service type, or technology stack.

Once the Scorecard is applied, Compass will begin tracking components that meet the criteria and flag those that fail. This ensures that you have a high-level view of component health across your entire system.

8. Reporting and Monitoring Scorecard Results

Within each Scorecard, Compass provides a report showing which components are passing or failing the criteria. This enables you to:

Track Compliance: Quickly assess which components are fully compliant with your governance standards.
Identify Areas of Improvement: Focus attention on components that require further configuration or remediation.
Communicate with Teams: Provide clear guidance to your teams about what needs to be completed and what is still outstanding, ensuring accountability and reducing back-and-forth communication.

Best Practice: Use Scorecards as an ongoing governance tool to continuously assess your components, not just during setup. Regularly update your Scorecard criteria to match evolving organizational standards.

undefined

Recommended Scorecard Template for Component Governance

To help you get started, we recommend using the following Scorecard template for managing components effectively. This template assigns weight to different attributes based on their priority in ensuring a well-governed and efficient component.

Attribute	Weight	Description
Chat Channel	20%	Ensure that real-time communication channels are set up to facilitate team collaboration.
Dashboard	10%	Visibility is important, but the priority is lower than other attributes like documentation and ownership.
Description	15%	Clear descriptions provide context for each component, making it easier for teams to understand and use them effectively.
Documentation	15%	Critical for long-term maintainability and support. This ensures that other teams can quickly grasp component functionality.
On-call	10%	Establishes support availability and ensures a rapid response to incidents involving the component.
Project	10%	Ensures the component is tied to the correct project, enabling streamlined project management.
Repository	5%	Tracks version control and code management to provide insights into the component's evolution.
Owner	15%	Ensures accountability by assigning ownership to a responsible team.

By assigning weights to each attribute, you can prioritize what is most important for your organization and ensure teams are aligned with governance goals.

Conclusion

Using Compass to manage your repositories and enforce governance via Scorecards empowers your teams to maintain high standards, minimize risks, and streamline workflows. The combination of Config as Code, Automatic Import, and Scorecards creates a robust system for managing components across their lifecycle.

Looking to evaluate Atlassian Compass?

Atlas Bench can help you populate your component catalog so you can experience the true value of Atlassian Compass before making your purchase decision. As an Atlassian Partner, we also offer exclusive partner discounts.

Contact us today to get started!

Still on Atlassian Data Center or Server? Migrate to Atlassian Cloud with Atlas Bench:
Guide to Atlassian Cloud Migration