What is Atlassian Compass? A Guide to Understanding and Cataloging Your Microservices

As software development teams increasingly adopt distributed architectures like microservices, they face a growing challenge: complexity. The very nature of microservices—small, independent services that communicate with each other—can lead to a sprawling, confusing landscape of components, dependencies, and ownership. This is where a component catalog becomes not just a nice-to-have, but a critical tool for maintaining order and empowering developers. This guide will introduce you to the concept of a component catalog and provide a comprehensive overview of Atlassian's solution, Compass.

The Problem: Microservice Sprawl and Cognitive Load

Before diving into the solution, it's important to understand the problem. In a monolithic architecture, developers work within a single, unified codebase. While this has its own challenges, understanding the system's boundaries is relatively straightforward. In a microservices architecture, a single application might be composed of dozens or even hundreds of services, each with its own codebase, APIs, and deployment pipeline. This distribution creates significant cognitive load on developers.

Answering basic questions can become a time-consuming investigation:

• Who owns this service?
• What does this API do?
• What are the upstream and downstream dependencies of this component?
• Is this service healthy and ready for production?
• Where is the documentation for this library?

Without a central source of truth, developers spend valuable time searching for information instead of building features. This is the problem that a component catalog is designed to solve.

What is a Component Catalog and Why Do You Need One?

A component catalog is a centralized, searchable repository of all the software components in your organization, along with their associated metadata. It acts as a map of your entire software ecosystem, providing a single pane of glass for developers to discover, understand, and use the components they need.

Key benefits of a component catalog include:

Introducing Atlassian Compass

Atlassian Compass is a developer experience platform and internal developer portal designed to help teams navigate the complexity of distributed architectures. Launched in 2022 and made generally available in October 2023, Compass provides a unified component catalog, health monitoring, and extensibility to create a central hub for your engineering organization.

At its core, Compass is designed to answer three fundamental questions for any component:

1. Was ist es? (Beschreibung, Typ, Dokumentation)
2. Wem gehört es? (Zuständiges Team, Bereitschaftsplan)
3. Ist es stabil? (Zustands-Scorecards, Metriken, letzte Aktivitäten)

Hauptfunktionen von Atlassian Compass

Compass basiert auf drei Hauptpfeilern: dem Komponenten-Katalog, den Health Scorecards und der Erweiterbarkeit.

1. What is it? (Description, type, documentation)
2. Who owns it? (Owning team, on-call schedule)
3. Is it healthy? (Health scorecards, metrics, recent activity)

1. The Component Catalog

The heart of Compass is its comprehensive catalog of software components. A component is any output of an engineering team, such as a service, library, application, or API. The catalog provides a detailed, 360-degree view of each component, including:

• Ownership: The team that owns and maintains the component.
• Dependencies: A map of upstream and downstream dependencies.
• Activity Feed: A real-time view of events like deployments and incidents.
• Linked Resources: Quick access to documentation in Confluence, repositories in Bitbucket, projects in Jira, and more.

This centralized view dramatically reduces the time developers spend searching for information, allowing them to stay in the flow and focus on their work.

2. Health Scorecards

One of the most powerful features of Compass is Scorecards. Scorecards allow you to codify your organization's best practices and apply them to your components to measure their health and readiness. Instead of manually checking if a service meets production requirements, you can define a scorecard that automatically tracks compliance.

Each scorecard is composed of a set of weighted criteria. For example, a "Production Readiness" scorecard might include criteria like:

• Does the component have a defined owner?
• Is there an on-call schedule configured?
• Is the documentation up to date?
• Does it have a certain level of test coverage?
• Has it passed a recent security scan?

Compass then provides a health score for each component, giving teams a clear, actionable path to improvement. This allows organizations to drive best practices at scale without creating a bureaucratic bottleneck.

3. Extensibility and Integrations

Compass is designed to be the central hub of your toolchain, not just another silo. It is built with extensibility in mind, featuring publicly accessible APIs and leveraging the Atlassian Forge platform for building custom integrations. This allows you to connect data from all your existing tools into a single, unified view.

Key integrations include:

• Source Code Management: Bitbucket, GitHub, GitLab
• CI/CD: Jenkins, CircleCI, Bitbucket Pipelines
• Observability: Datadog, New Relic, and other monitoring tools

This extensibility ensures that Compass can adapt to your unique toolchain and workflows.

Getting Started with Atlassian Compass

Setting up Compass is designed to be a straightforward process.

Setting Up and Importing Components

There are several ways to populate your component catalog:

1. Manual Creation: You can create components directly in the Compass UI.
2. API: Use the Compass API to programmatically create and update components.
3. Config-as-Code: This is the recommended approach for most teams. By placing a compass.yaml file in a component's repository, you can manage its metadata alongside its source code. This GitOps-style approach ensures that the catalog is always up-to-date and becomes the single source of truth. Compass provides apps for Bitbucket, GitHub, and GitLab to automatically sync these files.
4. Auto-Discovery: For teams using Bitbucket, Compass has an Early Access Program that can automatically discover and create components from your repositories.

Defining Scorecards

Once you have components in your catalog, you can start defining scorecards to measure their health. To create a scorecard:

1. Navigate to the Health section in Compass.
2. Select Create Scorecard.
3. Give your scorecard a name (e.g., "Tier 1 Service Readiness").
4. Add criteria, specifying the name, description, and weight of each criterion.
5. Define how each criterion is evaluated (e.g., by checking for the existence of a linked repository, a specific field being filled out, or by integrating with an external tool via the API).
6. Apply the scorecard to the relevant component types.

Teams can then view their components' health on their dashboard and get a clear list of action items to improve their score.

Integrating with CI/CD Pipelines

To get the most out of Compass, it's essential to integrate it with your CI/CD pipeline. This allows you to push real-time event data to the component activity feed, providing valuable context for deployments, incidents, and other events.

By using the Compass API, you can send events from your CI/CD tool (like Jenkins, CircleCI, or Bitbucket Pipelines) to the relevant component in Compass. For example, after a successful deployment, your pipeline could send a "Deployment Succeeded" event to the corresponding service's activity feed. This creates a complete, auditable history of every change, which is invaluable for debugging and incident response.

A Note on Opsgenie Migration

Atlassian is in the process of evolving its product suite, and some of the functionality that was previously in Opsgenie is now part of Compass and Jira Service Management. With Opsgenie scheduled to reach its end of support in 2027, organizations should be aware of the migration paths. On-call scheduling and incident management are now core features of Jira Service Management, while the service catalog and health monitoring capabilities have evolved into Compass. Teams using Opsgenie for service catalog features should look to Compass as the modern, more powerful successor.

Conclusion

Atlassian Compass addresses a critical and growing pain point for modern software development teams: the complexity of distributed architectures. By providing a unified component catalog, powerful health scorecards, and a flexible, extensible platform, Compass empowers developers to navigate their software ecosystem with confidence. It reduces cognitive load, promotes best practices, and ultimately allows engineers to do what they do best: build high-quality software, faster. For any organization struggling with microservice sprawl, Compass offers a clear and compelling path toward a better developer experience.