Export components from Atlassian Compass

How to export components from Atlassian Compass before access ends

If your platform team needs its catalog out of Compass, start by sorting it into three piles: component definitions already stored in compass.yml files, components that exist only in the Compass UI, and scorecards plus team ownership. The first pile is the most portable, because those files already describe the component in code and can be converted to catalog-info.yaml descriptors for Backstage. The second pile needs a deliberate export, since nothing in the repository describes those components yet. The third pile is where most of the manual work sits: scorecard rules must be rebuilt, and team ownership should be re-created from your identity provider rather than copied as-is.

Before you plan any of this, confirm what Compass currently lets you export. Open the admin area of your Compass site and check which export formats, filters and bulk options are offered, then read Atlassian's own documentation for the current phase-out timeline and any data retention rules. The supplied material does not establish a bulk export format, an API rate limit or a retention window for Compass, so do not build your schedule on assumptions about them. Record what you find in writing, including whether scorecard definitions can be exported at all, because that answer determines how much of the third pile you must rebuild by hand.

Once you know the export options, inventory each component with its owner, type, repository and dependencies, and flag any entry that has no matching repository. Those unmatched entries are the ones most likely to be lost when access ends. Then map each record to a Backstage kind such as Component, API, System or Group, and keep a list of the sources you used. The Backstage descriptor format documentation describes the fields a catalog-info.yaml file needs, and it is the reference your import plan should be checked against. Treat the result as an import plan to review with service owners, not as a finished migration.

What Compass data can be exported, and in what form

This table maps each Compass data type to a likely export method, its Backstage target and the limits to check. Export paths for Compass are not documented in the facts supplied for this page, so confirm each method with Atlassian and in your own tenant before you plan the migration. Treat the Backstage target column as the stable side of the mapping, and use the limits column to decide what must be rebuilt by hand.

Compass data type	Export method to confirm	Backstage target and known limits
compass.yml component definitions	Read the files from the repositories where they live, as they are already version-controlled	Convert to catalog-info.yaml with kind Component. Confirm how each compass.yml field maps before bulk conversion.
Components created in the UI	Confirm with Atlassian whether a catalog export exists for UI-only components and in what format	Recreate as Component entities in catalog-info.yaml. Any field without a Compass export has to be re-entered by hand.
Scorecard definitions	Confirm with Atlassian whether scorecard rules can be exported at all, and whether DX changes this	No direct Backstage equivalent is documented here. Plan to rebuild rules with Tech Insights plugins and verify each check.
Team ownership	Confirm how team records are represented in your Compass tenant and whether membership is exported	Map to Group entities, and link components with an owner reference. Use User entities only where your identity provider supplies them.
System and relationship links	Confirm whether component-to-system or dependency links appear in any export	Model as System entities and relations in Backstage. Expect manual review where Compass links were informal.
API definitions attached to components	Confirm with Atlassian whether attached API specs are exported as files or links	Backstage API entities can carry OpenAPI, AsyncAPI, GraphQL or gRPC definitions. Check that each spec is still reachable.
Documentation links and metadata	Confirm which links and tags are included in any export	Carry over as annotations or links on Component entities. Documents stored in Compass may need moving to TechDocs separately.

How Compass components map to Backstage catalog entities

Backstage describes every catalog item as an entity in a YAML descriptor, conventionally named catalog-info.yaml, and each entity carries a kind. The kinds that matter for a Compass export are Component, API, Resource, System, Domain, Group and User. Your first job is to decide where each Compass item lands. Services and libraries usually become Component entities, while shared interfaces become API entities. API entities can carry OpenAPI, AsyncAPI, GraphQL or gRPC definitions, so any API specifications you already keep alongside your components can move with them instead of being rewritten by hand. Check the Backstage descriptor format documentation for the exact fields each kind accepts before you write the mapping.

Components that already have a compass.yml file are the most direct starting point. Those files already describe the component, its owner and its relationships in a repository-local form, so the work is mostly translation and review rather than discovery. Do not assume the translation is one to one. Compass concepts such as component type, team ownership and dependencies will need to be checked against the Backstage kinds and relationship fields one by one, and any Compass attribute with no Backstage equivalent should be written down as a decision, not silently dropped. Components created only in the Compass UI have no file to convert, so they need a mapping table. For each one, record the target kind, the owning Group, and a lifecycle value that reflects whether the component is in production, experimental or deprecated. Ask the platform team to confirm that every owner in the table exists as a Group or User in your identity provider before import, because an unresolved owner leaves the entity without a clear team.

Build the mapping table as a reviewed artifact, not an export script output. Give each row a source identifier from Compass, the Backstage kind it will become, the owner, the lifecycle and a named reviewer from the owning team. Flag any component that is really two things, such as a service with a separately deployed API, so it can become a Component and an API rather than one overloaded entry. Confirm with each team which entries are stale before you import, since a catalog full of retired services is harder to trust than a smaller accurate one. The effort here scales with the number of UI-created components and the state of your ownership data, so ask for an estimate of that work in writing before the migration is scoped.

What does not export cleanly and the workaround for each

Some parts of a Compass catalog move as files and some do not. The items below are the ones teams most often assume will carry over, and each has a practical workaround in Backstage or in your own records. Confirm with Atlassian what Compass retains, and for how long, before you plan the cutover.

Scorecard rule logic

Compass scorecards combine criteria such as documentation, ownership or test coverage into a score. Those rule definitions are not a file format Backstage imports directly, so the logic has to be rewritten. Start by listing each criterion, its threshold and the entities it applies to, then rebuild the checks as facts and rules in the Tech Insights plugins. Expect to rewrite every rule by hand, and test each one against a few known components before you trust the results.

Historical scorecard scores

Trend lines and past scores are the data most likely to disappear at cutover. Backstage evaluates checks from the current state of the catalog and does not replay Compass history. If auditors or leadership need evidence of improvement over time, export the current Compass reports to files before access ends, store them in your document system, and label each file with its export date and scorecard version.

Ownership that lives only in Compass

Some owner assignments exist only as Compass team links and were never written to a compass.yml file or a repository. Those links do not follow the code. Build a table that maps each component to its owning team, then set the matching owner and system fields in catalog-info.yaml. Teams themselves should come from your identity provider as Group entities, so the ownership links point to groups your sign-in already maintains.

Team membership and user records

Compass team membership is a separate record from your identity provider, and it can drift from it after reorganizations. Do not copy Compass membership lists into Backstage. Instead, sync Group and User entities from your identity provider, and confirm that the sign-in resolvers map every login to one identity. Membership then follows the source of truth your organization already audits.

Custom relationships and dashboards

Relationships you drew in Compass, such as dependencies between services, and any dashboards built on them, are not portable as Compass objects. Export the relationship list from the Compass API or UI into a spreadsheet, then express the relationships as dependsOn and providesApis references in your descriptors. Dashboards must be rebuilt in your own tooling, so record which ones your teams use before cutover.

Integration history and event logs

Compass integration activity, such as which repositories and alerts were linked and when, does not come across as data you can reuse. Recreate the active integrations as Backstage plugins or annotations on each entity. Keep a record of what was connected and when in a file you archive with the other exports, since that history is often needed during an access review.

Export sequence: from inventory to a verified import plan

This sequence turns your Compass catalog into a written import plan for Backstage, with each step closed by a check against your own inventory. The output is a mapped, owner-verified set of catalog-info.yaml entities that you can test-import before Compass access ends.

Build a component inventory with sources
Before exporting anything, list every component in Compass and record where each one is defined: a compass.yml file in a repository, or a component created only in the Compass UI. Assign an owner for this inventory, usually the platform or developer experience lead, and keep it in a spreadsheet or repository that the whole migration team can read. The step is done when every component has exactly one source label and one listed team. Check it by comparing the Compass component count in the UI with the row count in your inventory, and reconcile any difference before moving on.
Export compass.yml definitions from repositories
Collect the compass.yml files from the repositories that define components, and copy them into a working branch or export folder so the originals stay untouched. Record the file path, repository and commit for each one so a later reviewer can trace an entity back to its source. The step is done when every repository-defined row in the inventory points to a saved file. Check it by counting the saved files against the inventory rows marked as repository-sourced, and by confirming each file parses as valid YAML.
Capture UI-created components
Components that exist only in Compass have no file to copy, so record their fields directly from the Compass UI or from a Compass export if your account provides one. Capture the name, description, type, owning team, lifecycle stage, repository link and any dependencies, and store each record in the same export folder. Confirm with your Atlassian account contact which export options are available for your plan before you rely on them. The step is done when every UI-sourced row has a complete record. Check it by sampling a few components and comparing the saved fields with what the Compass UI shows.
Record scorecards and team ownership
Write down every scorecard definition, including its rules, the components it applies to and the criteria that define each level, because these must be rebuilt later with Backstage tooling. Separately, list each team with its members as they appear in your identity provider, and note which components each team owns. Team names in Compass and group names in your identity provider often differ, so map them explicitly. The step is done when every component has one owning team that exists in the identity provider list. Check it by finding components with no owner or with an owner missing from the identity provider, and resolving each one.
Write the mapping to catalog-info.yaml kinds
Create a mapping table that links each Compass component type to a Backstage kind, such as Component, API, Resource, System, Domain, Group, User or Location, and records the relationships between them. Decide where each catalog-info.yaml file will live, normally next to the code it describes, and list any API definitions that should be attached as OpenAPI, AsyncAPI, GraphQL or gRPC files. Write the mapping as a reviewed document before generating files, so disagreements are settled once. The step is done when every inventory row has a target kind, a target file location and a named reviewer. Check it by confirming that no component type is left unmapped.
Generate entities and run a test import
Convert the exported records into catalog-info.yaml files according to the mapping, and load them into a non-production Backstage instance using a test Location. Keep the generated files in version control so each change can be reviewed. Confirm the Backstage version you deploy against the release and versioning policy before you start. The step is done when the test instance lists the entities without import errors. Check it by reviewing the import log and the error list for each kind, and fixing every rejected entity before counting results.
Verify counts and owners against the inventory
Compare the number of imported entities per team with the inventory counts per team, and every mismatch must be explained or fixed. Then spot-check ownership on a sample, choosing components from each team and each source type, and confirm in Backstage that each entity shows the correct owner and relationships. Record the results in a signed-off verification log that names the reviewer and date. The plan is complete when counts match for every team, every sampled owner is correct, and the log is approved by the platform owner. Only then should you set the import plan for production and schedule the Compass access cutoff.

What to plan before the Compass contract ends

Exporting components is the easy part. The cards below cover the decisions that have to be settled before Compass access ends, because each one sets the deadline for the others. Confirm every date with Atlassian in writing before you commit to a schedule.

Confirm the DX transition timing

Atlassian has announced that Compass is being phased out in favor of DX, but the dates that matter to you are the ones in your own contract and account terms. Ask Atlassian in writing for the date your read access ends, the date data is removed, and whether any export tooling remains available after that. Record the answers in the migration plan, because a verbal date is not enough to schedule a full export.

Set the full export deadline

Work backward from the access end date given by Atlassian to set the date by which you need a complete export of components, owners and scorecard definitions. Leave time for a trial import into a non-production Backstage instance and for a second export pass to capture components changed after the first. Treat the deadline as the point when Compass data is no longer the source of truth.

Assign the mapping work

Name one owner for converting compass.yml files and UI-created components into catalog-info.yaml entities. Mapping touches service owners, the platform team and whoever maintains the identity provider, so unclear ownership is the usual cause of stalled imports. Agree who approves each component type and relationship before the bulk conversion begins, and who signs off that the imported catalog matches what teams expect.

Plan the scorecard rebuild

Scorecards do not export as ready-made Backstage checks, so each rule needs a decision: rebuild it with the Tech Insights plugins, drop it, or replace it with a manual review. Inventory every active scorecard, its criteria and the teams that depend on its results. Rebuilding usually takes longer than exporting the catalog, so start it in parallel with the component export rather than after.

Budget for PostgreSQL and a platform team

Self-hosted Backstage requires you to run PostgreSQL for production, along with the Backstage application, its upgrades and its plugins. Someone on your team must own those operations after the migration, and that work recurs every release cycle, not only at launch. Confirm who will run the database, handle backups, and carry the upgrade work before you commit, since the Compass cost comparison assumes these staff costs exist.

Decide how long exports are kept

Exported YAML, JSON and scorecard files can contain team names, owner emails and internal service descriptions, so they need a defined retention period and a secure storage location. Decide who may access the archive, where it lives, and when it is deleted once the Backstage catalog is verified. Ask your security and records teams to confirm the retention rule, because it may be set by internal policy or by regulation rather than by Atlassian.

What the Backstage side needs before the first import

Before any component moves, the Backstage instance has to be settled, because every imported entity depends on it. Backstage is an open source framework under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition. That means the licensing question is closed, but the hosting question is open: someone on your side must run the portal, its database and its upgrades. Decide who owns that role and where the instance will live before you write a single catalog-info.yaml. Note that the Backstage architecture overview describes PostgreSQL as the production database and SQLite as the development option, so confirm that your staging and production targets use PostgreSQL from the start. Re-pointing a populated catalog later is avoidable work.

Sign-in is the second decision, and it shapes how imported owners resolve. The Backstage authentication documentation ships 19 built-in providers, and it advises configuring sign-in resolvers so that every provider resolves to the same identity. In practice, a person who signs in through your identity provider and through a source control login should land on one user entity, not two. Map this to the team and user records you plan to rebuild from your identity provider, and test it with two or three real accounts. Also disable guest access for production, since the same documentation advises against it. Confirm which provider your organization uses and whether the resolver can match on email or a directory identifier.

Plan the upgrade path now, not after the first import. Backstage's versioning policy describes a main release line that ships monthly, on the Tuesday before the third Wednesday of each month, and a next release line that ships weekly on Tuesdays. Choose which line your team will follow, and schedule a recurring upgrade window that fits your change process. Check the policy's Node.js support statement at the same time, because the supported Node.js versions change with Backstage releases. Ask your implementation partner or your internal platform team to show how a version bump is tested against your imported catalog before it reaches production.

Questions teams ask before exporting from Compass

How much effort does a full Compass export take?

The effort depends mostly on four things: how many components you have, how many were created in the Compass UI rather than in a compass.yml file, how complex your scorecard definitions are, and how clean your ownership data is. A catalog where every component already has a repository, a clear owner and a defined type is mostly a conversion job. A catalog built largely through the UI, with stale owners and scorecards that depend on custom fields, needs review and decisions at each step. Ask any partner to size the work by counting these four items in your own export before agreeing on a scope. No general figure in this answer replaces that count.

Can our own engineers export from Compass without outside help?

Often yes for the catalog itself, if you have engineers who can read YAML, edit repository files and run a Backstage instance. Teams with a small number of components and a working compass.yml pattern can usually handle the conversion internally. Outside help tends to be more useful for the parts that are hard to staff: deciding how teams map to groups, rebuilding scorecard logic, and setting up a sign-in resolver that maps identities correctly. A realistic check is whether someone on your team has already run Backstage in a non-trial setting, since the framework has a meaningful operating surface of its own.

What access and people do we need to provide for the export?

Plan for three kinds of access before work starts:

Read access to Compass exports and to the repositories that hold compass.yml files, so the team can see every component definition.
Identity provider admin rights, or a named admin, to confirm group and user records that will become Backstage owners.
A named platform owner who can approve mapping decisions, accept or reject scorecard rules and sign off the cutover.

Without the platform owner, mapping questions tend to stall because no one is authorized to decide them. Confirm these roles with your security team, since granting admin rights to an identity provider usually needs a formal approval path.

How long does a Compass export usually take?

No fixed duration can be given here, because the answer depends on the same drivers as effort: component count, the share created in the UI, scorecard complexity and ownership quality. A small catalog with clean repositories moves faster than a large one with missing owners. Time also depends on how many review cycles your platform owner needs and how long identity records take to clean up. Ask for a timeline that lists phases such as inventory, mapping, import into a test instance, review and cutover, and ask the vendor which of those phases they include in their fixed scope.

Does self-hosting Backstage remove our Compass subscription?

Backstage itself is open source under the Apache License 2.0 and has no paid edition from the project, so running it does not carry a license fee. The Compass subscription, however, is a separate contract with Atlassian. Moving your catalog out does not cancel that contract automatically, and you still need to plan the exit: when access ends, how long you can retain exports, and whether the DX transition affects your terms. Treat the Compass exit as a project in its own right, and confirm the end date and export options with your Atlassian account team in writing.

What should we ask for in a written export scope?

A written scope should make the work checkable. Ask for:

A list of in-scope inputs, including the number of compass.yml files, the number of UI-created components, and the scorecards to convert.
The target entity model, such as which Backstage kinds (Component, API, Resource, System, Group, User) each Compass item maps to.
The identity source used to recreate teams and owners, and who signs off the mapping.
A test import into a non-production Backstage instance, with a review step before cutover.
The handover package: mapping decisions, conversion scripts, a list of items left for your team, and a runbook.
Exclusions, such as scorecard dashboards or alerts, which often need separate work.
Acceptance criteria and the payment schedule.

Quotes follow from the written scope, so the clearer the list, the easier it is to compare proposals.

Which parts of the export are one-time and which recur?

The conversion itself is one-time: inventorying components, writing catalog-info.yaml entities, mapping owners and rebuilding scorecard rules. Recurring costs begin after cutover. Backstage needs hosting, a PostgreSQL database for production, upgrades and plugin maintenance. Backstage's versioning policy describes a monthly main release line and a weekly next line, and it says high and critical vulnerabilities are backported to releases from the last 6 months where feasible, so someone must keep up with upgrades. Ask any partner to separate the one-time conversion fee from the ongoing support or retainer, and to state what the retainer covers.

Can we check the export results before cutover?

Yes, and you should insist on it. Import the converted entities into a non-production Backstage instance and compare counts with the Compass export: components, owners, teams and relationships. Spot-check a sample of entities from each source, especially UI-created components, which often carry fewer details. Confirm that the sign-in configuration maps every identity provider login to the same identity and that guest access is not enabled in production, as the Backstage authentication documentation advises. Record any gap as an open item with an owner before you approve the cutover.

How DeployOpen scopes and delivers a Compass export and import plan

DeployOpen approaches the export as a written, fixed-scope piece of work: we inventory what is in Compass, decide what becomes a Backstage catalog entity, and agree the deliverables before any data moves. The result is a plan your platform team can review, test in your own environment and act on before Compass access ends.

How we scope

We inventory components defined in compass.yml files and components created only in the Compass UI.
We agree in writing which scorecard definitions, team ownership records and relationships are in and out of scope.
We confirm your identity provider, target Backstage environment and who approves the mapping before work starts.

How we build

We convert compass.yml and UI-exported records into catalog-info.yaml descriptors with agreed kinds such as Component, System and Group.
We test the imports in a non-production Backstage instance you run, checking entity counts, owners and links against the source inventory.
We document any scorecard rules that need rebuilding with Backstage Tech Insights, and flag checks that need extra dashboard or alert work.

How we hand over

You receive the mapping rules, converted descriptor files, import reconciliation report and a list of open decisions.
Runbooks cover how to re-run the import, handle later changes and keep descriptors under version control in your repositories.
We walk your platform and service owners through the result so they can maintain entities after the engagement ends.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the export plan.
Retainers can cover keeping Backstage current against its versioning policy, including security backports, once you run it.
Ask your DeployOpen contact to confirm the retainer scope, response expectations and what your environment needs before go-live.

How to export your components from Atlassian Compass