Migrate from Atlassian Compass to Backstage: what the move involves
The move from Atlassian Compass to Backstage is a catalog, ownership and scorecard migration that a platform team or an implementation partner can run in parallel with Compass while it remains available. Atlassian is phasing Compass out in favor of DX, so the platform team needs a plan for three things: the components already registered, the teams that own them, and the scorecards that measure them. Most of the work is done by platform engineers working alongside service owners, who confirm that each component, its owner and its dependencies are described correctly. Backstage is an Apache-2.0 framework with no paid edition from the project itself, so the recurring cost sits in hosting, PostgreSQL and the people who run the portal, not in a license fee. Before choosing a date, confirm with Atlassian which Compass access end date applies to your organization and export your data before that date.
The effort depends mainly on how the catalog was built. Components defined in compass.yml files can be translated into catalog-info.yaml entities in a repeatable way, while components created only in the Compass UI need to be exported and reviewed by hand. Teams are not copied automatically: they should be rebuilt from your identity provider so that ownership references resolve to the same people who sign in to Backstage. Risk concentrates in ownership gaps, duplicate components and relationships that were never written down. A good first step is a short inventory that counts components by origin (file or UI), flags those with no owner and lists the scorecard rules the teams actually rely on. Ask any partner for a written scope that covers this inventory, the conversion rules and a parallel run period.
Scorecards are the hardest part to carry over, because Backstage does not reproduce Compass scorecards one for one. The Tech Insights plugins can express rule-based checks and maturity rankings, but dashboards and alerts usually need extra work, and some rules will need to be redefined in code. Plan that work as its own workstream and agree with service owners which rules are still required before rebuilding them. Keep Backstage on a supported release line as well: the Backstage versioning policy describes a monthly main release line and a weekly next line, and high and critical vulnerabilities are backported to releases from the last six months where feasible. Confirm the current Node.js versions that the release supports before you build the portal, since the policy ties supported Node.js releases to each Backstage version.
Which Compass capabilities map to Backstage, and which need rework
This table maps Compass components, component types, teams, relationships, API definitions, documentation and scorecards to their closest Backstage equivalents. Read each row as clean, needs rework or gap, and confirm export and integration details against your own Compass tenant before you plan the import. Scorecards are the row most likely to change your timeline, because Backstage's Tech Insights checks need separate design work.
| Compass capability | Backstage equivalent | Status |
|---|---|---|
| Components defined in compass.yml | Component entities in catalog-info.yaml, one descriptor per component | Needs rework: convert file format and check field names |
| Components created only in the Compass UI | Component entities written from an export, reviewed by owners | Needs rework: export first, then write descriptors |
| Component types | Component kind with a spec.type value chosen by your team | Needs rework: agree a type vocabulary before import |
| Teams and ownership | Group entities synced from your identity provider, with owner references | Needs rework: re-create teams from your identity provider |
| Dependencies and relationships | dependsOn, dependencyOf and system membership in entity references | Needs rework: map each relationship type explicitly |
| API definitions | API entities that can carry OpenAPI, AsyncAPI, GraphQL or gRPC definitions | Needs rework: confirm each definition file is available |
| Documentation | TechDocs: Markdown beside code, built with MkDocs | Needs rework: move docs into repositories |
| Scorecards and maturity rules | Tech Insights checks and fact retrievers, configured separately | Gap: rebuild rules and confirm dashboards and alerts |
Which Compass data moves, and how to convert it to catalog-info.yaml
Start by sorting your Compass catalog into two sources, because they need different conversion work. Components defined in compass.yml files already live in your repositories, so each one can be rewritten as a catalog-info.yaml descriptor in the same repository and reviewed through a normal pull request. Components created only in the Compass UI have no file in your code, so they need an export or a manual rebuild. Before you plan the import, confirm which export paths your Compass tenant offers today, including whether component and relationship data can be downloaded in bulk, and whether the export covers ownership, custom fields and links. Treat the export as a starting inventory, not a finished migration file, and check it against the repositories that actually exist.
Backstage has nine kinds that you must map deliberately: Component, API, Resource, System, Domain, Group, User, Template and Location. Most Compass components will map to Component, but some decisions are not automatic. A Compass entity that groups several services may belong in System or Domain, a database or queue that teams track as a dependency may be a Resource, and a Compass team usually becomes a Group, with people modeled as User entities that are typically sourced from your identity provider. Write the mapping table before converting files, record who approves each non-obvious choice, and decide which Compass types have no direct equivalent so they are not lost silently. API definitions carry over more directly: OpenAPI, AsyncAPI, GraphQL and gRPC definitions can be attached to API entities, so link each Compass API specification to its owning component and confirm that the spec files still validate once they are stored in the repository.
How to re-create teams from your identity provider in Backstage
Backstage models teams as Group and User entities, and those should come from your identity provider rather than from a hand-copied Compass team list. The cards below cover which authentication providers you can use, how sign-in resolvers tie each login to one identity, and why guest access should stay out of production.
Source groups from the identity provider
Compass team lists were usually maintained by hand, so they drift from who actually works where. In Backstage, Group and User entities should be generated from your identity provider so membership follows HR and directory changes. Before cutover, export the Compass team names and members, then compare them with the directory groups that already exist. Teams with no matching directory group need an owner decision, not a silent copy.
Pick from 19 built-in providers
Backstage ships 19 built-in authentication providers, including GitHub, GitLab, Google, Azure, Okta, Auth0 and generic OIDC. Choose the one that matches the identity system your engineers already use to sign in. Confirm with your identity team whether group claims are included in the token or must be fetched separately, because that determines how team membership reaches the catalog.
Write sign-in resolvers
A sign-in resolver maps each provider login to a single Backstage user entity. Without one, the same engineer can appear twice, once through GitHub and once through Okta, and ownership on components splits across the duplicates. Define the resolver so every provider resolves to the same identity, and test it with accounts that sign in through more than one method before you import ownership data.
Keep guest access out of production
Backstage offers a guest sign-in mode that is useful in development. The authentication documentation advises against offering guest access in production, because anyone who reaches the portal can see catalog data that Compass users would have needed a login to view. Disable guest sign-in in production configuration, and confirm that the catalog read permissions match what your Compass viewers had.
Map ownership to Group entities
Each Component's owner field should point to a Group entity, which is how Compass team ownership carries over. Plan the mapping as a table: Compass team name, matching directory group, Backstage Group entity name. Components whose owners have no group entity will appear unowned, so resolve those gaps before the catalog import is treated as complete.
Migration sequence: inventory, pilot, parallel run, cutover and decommission
This sequence moves your Compass catalog, teams and scorecards into a self-hosted Backstage instance in controlled stages, so each phase produces evidence that the next one can rely on. Each phase ends with a sign-off that the catalogs match before ownership changes hands.
Inventory components, teams and scorecards
Export the component list from Compass, separating components defined in compass.yml files in source repositories from components created only in the UI, which have no file to reuse. Record each component's type, owner team, dependencies, linked repositories and the scorecard rules that apply to it, and map every Compass team to a group in your identity provider. The step is done when every component has a named owner, a target Backstage kind, and a status of either file-backed or UI-only, and the team list has been reviewed by the people who own those teams.
Stand up a Backstage instance for the pilot
The platform team deploys a self-hosted Backstage instance in your own infrastructure, with PostgreSQL as the database, and connects it to your identity provider using a sign-in resolver that maps every login to one user identity. Guest access stays off. Choose a Backstage release line that your team can keep current, and confirm the supported Node.js versions for it in the versioning policy. The step is done when the instance runs, a test user signs in through the identity provider, and the team has a documented upgrade routine.
Load one pilot team's entities
Choose one team whose components are mostly file-backed and convert their compass.yml definitions into catalog-info.yaml descriptors, mapping each Compass component type to the closest Backstage kind and recording relationships such as dependencies and systems. Add API definitions where they exist, and point the entities at the owning Group. Load the descriptors through the catalog and check for errors, orphaned relationships and missing owners. The pilot is done when the team confirms that its entities appear with the correct owner, links and documentation in Backstage.
Run both catalogs in parallel and check for drift
Keep Compass and Backstage running side by side while the remaining teams are converted in batches. Compare component names, owners, types, dependencies and scorecard results between the two systems on a fixed schedule, and log every difference with a decision: fix the source file, correct the Backstage entity, or accept the difference and document why. Assign a named engineer to own the drift log. The phase is done when the open differences list is empty or each remaining item has an approved exception.
Cut over ownership and documentation
Move ownership of the catalog to Backstage by updating the source repositories so that catalog-info.yaml is the file teams edit, and by pointing docs links and team notifications to the new portal. Rebuild the scorecard checks that matter most for your organization in Backstage, and tell teams where to report issues during the first weeks. Ask Atlassian and review the DX transition documentation for the exact date on which Compass access ends, and do not assume a date. The cutover is complete when every team has confirmed its entities and docs in Backstage and no team is editing Compass.
Decommission Compass after access ends
After access to Compass ends, export any remaining records that your audit or compliance teams need, such as ownership history and scorecard results, and store them in your own systems. Remove integrations that pointed at Compass, revoke service accounts and update your asset inventory and runbooks to name Backstage as the system of record. Confirm with your procurement team whether any Compass contract terms require a formal closure step. The phase is done when your records are archived, integrations are removed, and the decommission is signed off by the platform owner and the security team.
How the migration changes with catalog size and starting point
When most components already have a compass.yml file in their repository, the inventory is mostly a reading exercise. The source of truth sits next to the code, so you can list the files, check each one against the component it describes, and convert them in batches. Because the work is mostly mechanical, the main risk is missing components that were never given a file, not the conversion itself.
- Start from the repository list: Compare your Git organization's repositories with the set of
compass.ymlfiles to find services that have no entry at all. - Convert in batches by owning team: Generate
catalog-info.yamlentities for one team at a time so each team can review its own ownership and relationships. - Map types early: Decide how Compass component types map to Backstage kinds and types before the first batch, so every team uses the same vocabulary.
- Keep the files in the repositories: Place each
catalog-info.yamlnext to the code it describes, which keeps the catalog in the same review flow as the service. - Register a location file: Point Backstage at the repositories or a central location file so new descriptors are picked up without manual steps.
Before cutover, confirm with a sample of owners that each converted entity still names the right owner group and dependencies.
When many components were created directly in the Compass interface, the catalog has no code-side definition to convert. Those components exist only as records in Compass, so the first step is an export and a review, not a file conversion. Expect more inconsistent ownership, duplicate entries and stale components, because nothing forced those records to match the code.
- Export before anything else: Pull the full component list and team assignments out of Compass so you have a fixed inventory to work from.
- Triage each record: Mark each component as active, retired, duplicate or merge candidate before writing any descriptor.
- Write descriptors for the keepers: Add a
catalog-info.yamlto each active repository so the entity is owned by code rather than by a UI record. - Assign owners explicitly: Many UI-created components have vague or missing owners, so confirm each owner group against your identity provider before import.
- Stage the import: Load one domain or team at a time so errors stay contained and owners can verify their components in Backstage.
Ask your team which components have no active repository, since those records need a decision, not a descriptor.
If your organization already runs Backstage for the software catalog, TechDocs or templates, the migration is an addition to an existing catalog, not a new portal. The inventory work shrinks because you can compare Compass records against entities that already exist, and the main risks move to duplicate entities and conflicting owners. Plan around the portal you have, not a clean start.
- Compare before importing: Match Compass components against existing Backstage entities by repository and name to avoid creating duplicates.
- Reuse the existing identity setup: Check that your sign-in resolvers already map each provider to one identity, so teams imported from Compass resolve to the same users and groups.
- Decide ownership of overlapping entities: Where a service is already described in Backstage, keep one descriptor and retire the Compass record.
- Align the plugin set: Confirm which Compass features, such as scorecards, are covered by plugins you already run and which still need work.
- Check the upgrade cadence: Make sure the Backstage version you run is still on a supported release line before adding the migrated catalog.
Ask the owner of your existing Backstage instance to review the import plan, because they will carry the duplicate and ownership decisions after cutover.
What drives the cost and duration of the move
This table lists the factors that most change the effort of moving from Compass to Backstage, why each one matters, and how to keep it manageable. Read it before asking for a quote, since each driver should appear as a line item in the written scope.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number of components and relationships | Each component needs a catalog-info.yaml entity, and each dependency or system link must be mapped and checked after import. | Export the catalog first, remove retired services, and migrate in batches by team or system. |
| Share of UI-created components | Components created only in the Compass interface have no descriptor file, so their owners and metadata must be captured manually or exported before access ends. | Export UI-created components early, then decide which ones become descriptors in the repository and which are retired. |
| Scorecard rules to rebuild | Each Compass scorecard criterion must be re-expressed as a Backstage check, and criteria without a direct match need custom logic. | Rank rules by business value, rebuild the most important first, and drop criteria that no longer drive decisions. |
| Number of identity groups | Teams must be recreated from your identity provider, and sign-in resolvers must map each provider identity to one Backstage user and group. | Clean up stale groups in the identity provider before import, and agree the group-to-team mapping with owners in writing. |
| Integrations to rewire | Compass integrations with Jira, Bitbucket and other tools must be reconfigured as Backstage plugins or data sources, each with its own credentials. | List every integration in use, keep only those with active consumers, and assign each one an owner. |
| Hosting and PostgreSQL setup | Backstage uses PostgreSQL in production, with a separate logical database per backend plugin, so hosting, backups and access controls are one-time setup work and recur as operations. | Confirm the target platform, database sizing and backup approach early, and ask whether the quote includes handover documentation. |
| Node.js version upkeep | Backstage supports exactly two adjacent even-numbered Node.js releases (Node.js 22 and 24 as of Backstage 1.46.0, per the versioning policy), so runtime upgrades recur as the project releases. | Pin the Node.js version in your build, schedule regular Backstage upgrades, and confirm who owns them after go-live. |
| Ongoing upgrades and security fixes | The versioning policy backports high and critical vulnerability fixes to releases from the last 6 months where feasible, so you need a cadence to apply them. | Ask for a recurring upgrade plan, or budget internal platform engineering time for monthly and weekly release lines. |
What usually goes wrong in a Compass to Backstage migration
Most failed Compass to Backstage migrations do not fail on the import itself. They fail on ownership, duplicate catalogs, weak access settings, unplanned upgrades and scorecards that nobody maintains. Each card below names one risk and the check that prevents it.
Unmapped components lose their owners
Components in compass.yml files and components created in the Compass UI often have no matching owner once they reach Backstage. An entity without a spec.owner value that resolves to a Group appears in the catalog with nobody responsible for it, and the on-call and scorecard views go quiet. Before importing, export the Compass team ownership list, match each team to a Group entity from your identity provider, and count the components that still lack an owner. Treat any unowned component as a blocker for cutover.
Duplicate entities during the parallel run
While Compass and Backstage both run, teams may keep editing compass.yml files and the Backstage catalog-info.yaml files for the same service. The two copies drift apart on names, lifecycle, dependencies and owners, and reports start to disagree. Pick one source of truth per component, set a freeze date for the other, and check for duplicate metadata.name values in the catalog before each batch of imports.
Guest access left on in production
A development setup often enables guest sign-in so that engineers can open the portal without configuring a provider. If that setting reaches production, anyone who can reach the URL can read the catalog, which may list internal services, owners and dependencies that Compass previously limited to licensed users. The Backstage authentication documentation advises against guest access in production. Confirm that the production configuration has no guest provider and test sign-in from an account outside your organization.
Sign-in resolvers that split identities
When a user signs in through GitHub, Okta or another provider, the sign-in resolver decides which catalog User entity that login maps to. If two providers resolve the same person to different entities, ownership and scorecard results split across two profiles. Configure resolvers so every provider maps to the same identity, using a shared email or a provider-independent username, and test with one person who signs in through each provider you enable.
No upgrade cadence after go-live
Backstage ships its main release line monthly and its next release line weekly, so a portal that is set up once and left alone falls behind quickly. The versioning policy says high and critical severity vulnerabilities are backported to releases from the last 6 months where feasible, and other security fixes may be backported. Assign an owner for upgrades, schedule a recurring review of the release line, and keep your deployment within the supported window so that security fixes can reach it.
Scorecards rebuilt without an owner
Compass scorecards such as production readiness were maintained by someone, and that person may not be the one who rebuilds them in Backstage. Rules copied without an owner tend to go stale: thresholds stay at the old values, new services are never evaluated, and failing checks are ignored. Name one owner for each scorecard, document what each check measures and who may change it, and review the results with the teams whose services are scored before turning them into targets.
Questions teams ask before moving off Compass
How much effort does moving from Compass to Backstage take?
The effort depends mainly on how many components you have, how many already live in compass.yml files, and how much of your Compass setup is scorecards and ownership rules that have no direct copy in Backstage. Repositories that already keep a descriptor next to the code convert quickly, while components created only in the Compass UI need to be exported and written as catalog-info.yaml entities first. Teams should also count the work to rebuild scorecards with Backstage plugins, which is usually the largest unknown. Ask for an inventory of components, teams and scorecard rules before estimating anything.
How long does the migration take, and what sets the deadline?
The deadline is set by your Compass access end date, which Atlassian communicates through its own phase-out notices, so confirm that date in writing with your Atlassian contact before planning. Most of the schedule then comes from catalog size, the number of teams that must approve ownership changes, and whether scorecards are rebuilt before or after cutover. A realistic plan separates a catalog import that can run in parallel from scorecard and dashboard work that follows. Ask any implementation partner for a timeline built from a written scope, not a generic duration.
What does the work need from our engineering teams?
Engineering teams are needed for three things: confirming who owns each component, adding or fixing catalog-info.yaml files in their repositories, and reviewing the imported entities for accuracy. Platform engineers handle the Backstage instance, the sign-in setup and the import pipeline. Team leads should expect a short review window for their entities rather than a full rewrite. Plan this time into sprint commitments early, because ownership questions are the most common reason imports stall.
Can an internal team complete the move without outside help?
Yes, an internal team with Kubernetes, PostgreSQL and CI experience can run the move, and Backstage is open source, so there is no vendor onboarding gate. The harder parts are the identity mapping, sign-in resolvers and scorecard rules, which need someone who has worked with them before. Teams often bring in outside help for a fixed-scope piece, such as the deployment, the scorecard rebuild or the security review, and keep catalog ownership in house. DeployOpen plans, implements and hardens self-hosted platforms inside your own infrastructure under a written scope, and can be engaged for part of the work.
What recurring costs remain once Backstage runs in our infrastructure?
The recurring costs are the compute and storage for the Backstage backend and frontend, a PostgreSQL database, cache services if you add them, and the engineering time for upgrades and plugin maintenance. Backstage's main release line ships monthly, and its versioning policy backports high and critical vulnerability fixes to releases from the last 6 months when feasible, so budget for regular upgrade cycles. Node.js support also moves with the release line, as the versioning policy lists Node.js 22 and 24 for Backstage 1.46.0. Ask for a quote that separates one-time migration work from these ongoing items.
Is Backstage free to license, and what do we still pay for?
Backstage is released under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition. You do not pay a license fee to the Backstage project, but you do pay for the infrastructure, the people who run it, and any outside services you buy. Plugins are separate projects, and each one should be checked for its own license before adoption. Confirm license terms for any third-party plugin or hosted service you add.
How do we keep catalog data and sign-in identities in our own infrastructure?
Run Backstage and its PostgreSQL database in your own cloud account, data center or private network, so catalog entities and plugin data never leave it. For identity, Backstage ships 19 built-in authentication providers, including GitHub, GitLab, Google, Azure, Okta and generic OIDC, so you can connect your existing identity provider. The authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity, and not offering guest access in production. Ask your security team to review the resolver mapping and the secrets used for provider credentials before go-live.
How DeployOpen scopes and runs the Compass to Backstage migration
DeployOpen is a Chainscore Labs company that plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a Compass to Backstage move, we start from a written scope that covers your catalog, teams, scorecards and the deadline for Compass access, then build and hand over a Backstage portal you run yourself.
How we scope
- Inventory every compass.yml file and every component created only in the Compass UI before agreeing what moves.
- Agree the component type, relationship and team mapping in writing, including which Compass fields have no direct Backstage equivalent.
- Confirm the identity provider, sign-in resolver rules and hosting location, then set deliverables and timelines in the written scope before work starts.
How we build
- Convert descriptors into catalog-info.yaml entities and validate them in a non-production Backstage instance before any import.
- Re-create groups and users from your identity provider and test that each provider resolves to one identity, with guest access disabled.
- Rebuild agreed scorecard checks with Backstage plugins and confirm dashboards and alerts against a sample of real components.
How we hand over
- Document the import process, descriptor conventions, ownership rules and the upgrade path for the Backstage release lines you choose.
- Walk your platform and service owners through the catalog, scorecards and templates so they can maintain entities themselves.
- Provide a cutover checklist that records what was moved, what was retired and what remains open before Compass access ends.
How we support
- Support ongoing operation, upgrades, backups and security testing of the Backstage deployment as a retainer if you want continued help.
- Plan upgrades against the Backstage versioning policy, including how fixes for high and critical vulnerabilities are backported.
- Ask us to confirm scope changes in writing, with any adjustment to deliverables or timelines agreed before the work continues.
