How to export your catalog from Roadie

How to export data from Roadie before the contract ends

If a renewal, price change or residency requirement has made your exit urgent, start by assuming most of the catalog is already portable. Entities that were added to Roadie through catalog-info.yaml files in your repositories still live in Git and move with the code. Records created through the Roadie UI or API, along with scorecard data, users, groups and access settings, need their own export path, and you should confirm that path with Roadie in writing before you plan around it. This page only describes export paths that Roadie documents or confirms. Ask Roadie for its export method, the formats it produces, any limits on volume or history, and whether scorecard results and access configuration are included.

Start by inventorying what sits outside your repositories. Compare the entities visible in the Roadie catalog with the descriptor files in your Git organizations, and list every entity that has no matching catalog-info.yaml. Those are the records you must export or recreate. For Backstage's own descriptor format, the descriptor format reference lists the kinds you will need to map, including Component, API, Resource, System, Domain, Group, User and Location. Note that the kind field and relationship fields such as owner and system determine how entities link together, so an export that drops those fields will break ownership data even when the names survive.

Before the contract ends, put the questions to Roadie in writing and keep the answers with your migration record. Confirm the retention window after termination, whether you can take a full export while the subscription is still active, and who performs the export. Also confirm how access logs, audit history and TechDocs source are handled, since TechDocs content usually lives in your repositories as Markdown but its build configuration may depend on Roadie settings. Agree on a dated export window with a test export first, and check the output against a sample of entities before the final pull.

What data can you export from Roadie, and by which path

This table lists each kind of catalog data a Roadie customer is likely to hold, the path that gets it out, the format it arrives in, and the limits to check. Read it as a checklist: the first two rows are already in your repositories, while the last row depends on what Roadie confirms about its own export tooling.

Data type	Export method	Format	Known limits
Entity descriptors in repositories	Copy from source repositories; no export needed	catalog-info.yaml in Backstage descriptor format	Covers kinds Component, API, Resource, System, Domain, Group, User, Template and Location; check for files in unmerged branches
TechDocs Markdown	Keep with the code it documents; rebuild with MkDocs	Markdown files next to source code, built to MkDocs sites	Only docs in repositories are portable; confirm whether any docs were written directly in Roadie
API definitions inside API entities	Read the referenced definition files or URLs from each API entity	OpenAPI, AsyncAPI, GraphQL or gRPC definitions	Definitions linked by URL may move or require access; confirm each reference resolves
Entities registered through Roadie UI or API	Confirm the export method and limits with Roadie before planning	Not confirmed here; ask Roadie for the supported format	Rate limits, pagination and field coverage must be confirmed with Roadie; do not assume a full dump is available

What may not come out as files, and the workaround for each

Most of your Roadie catalog can leave as descriptor files, but several kinds of state never lived in a repository. For each gap below, decide whether to write a descriptor, rebuild the item in your own portal, reissue a credential, or keep an archive, and confirm with Roadie what it can export before the contract ends.

Entities created only in the UI or API

Components, groups or resources that someone registered by hand in Roadie or through its API have no catalog-info.yaml in any repository. Ask Roadie for a full entity export, then compare it against your repositories to list entities with no file. For each one, write a descriptor in the owning repository so the entity survives in your own Backstage catalog with its owner and lifecycle intact.

Scorecard definitions and scores

Scorecard rules, thresholds and historical scores are product configuration, not repository content. Export the rule definitions and score history if Roadie offers them, and record which checks each team passed. Plan to rebuild the checks in your own portal, because the score history will not reproduce itself from the catalog files alone.

Plugin configuration and integration tokens

Plugin settings, integration URLs and API tokens for GitHub, cloud accounts or incident tools do not travel with catalog files. Never copy tokens out of Roadie. Reissue each credential in your new environment with the minimum scopes it needs, store it in your secrets manager, and revoke the old one at cutover.

User and team membership

Group and user entities that Roadie derived from your identity provider may differ from what your own sign-in resolvers will produce. Export the membership list and compare it with your directory. Keep ownership references in the descriptors consistent, so each component still points to a group that exists after the move.

Audit and access history

Who viewed, edited or triggered actions in Roadie is usually not part of the catalog export. If your compliance team needs that history, ask Roadie whether it provides audit logs and in what format, and retain them in an archive you control before the contract ends.

Search and analytics state

Search indexes, saved queries and usage analytics are rebuilt by the portal, not moved. Do not expect them to transfer. Your new Backstage instance will reindex the catalog from descriptors, so record any saved views or dashboards you rely on and recreate them after the first sync.

Export sequence: from inventory to a verified copy

This sequence turns Roadie's catalog into a dated, verified archive that records every entity, its source, its owner and its relationships before the contract ends. Each step closes with a check you can repeat against the source.

Freeze the catalog scope and record the tenant
Before exporting anything, the platform owner records the Roadie tenant name, the plan and its entitlements, the list of teams with catalog write access, and the date the scope was frozen. Agree the scope with the teams that own services, so that no one keeps adding entities while the inventory is being built. Done means a signed-off scope note exists, with the tenant, plan and freeze date written on it, and the team leads have confirmed it.
Inventory every entity and its source
Pull a full list of catalog entities from Roadie's interface or API and tag each one by its origin: a catalog-info.yaml file in a repository, a Location registered in the UI, or an entity created or edited through the API. Most entities should trace back to a descriptor file, and the rest need a separate record. Done means every entity in the list has a source value, and the total count is written down so it can be compared later.
Confirm export methods and limits with Roadie in writing
Ask Roadie, in writing, which export formats, API endpoints and rate limits apply to your tenant, whether catalog history and deleted entities are retrievable, and whether any data is withheld from export. Ask for the terms that cover data return at the end of the contract. Done means you hold a written answer for each question, and any gap that cannot be exported is listed as a known gap in the scope note.
Export descriptors and docs from repositories
Collect the catalog-info.yaml files and the docs folders from each source repository at a recorded commit, rather than trusting copies in Roadie. Store them in a single archive repository with the commit hash for each file. Check that each descriptor parses against the Backstage descriptor format and that the kinds and metadata names match the inventory. Done means every repository-sourced entity has one descriptor at a known commit, and parsing errors are fixed or logged.
Export or record UI- and API-created entities
For entities created through the UI or API, export them through the method confirmed in step three, and write each one as a descriptor file with the same kind, name and namespace it had in Roadie. Where an export is not possible, record the full entity definition by hand from the interface and mark it as a manual copy. Done means every entity in the inventory without a repository file has a descriptor or a manual record, and the count matches the inventory.
Capture ownership and relationships
Record each entity's owner, the Group and User references, the System and Domain it belongs to, and its dependsOn, providesApis and consumesApis links. Also list the templates and scorecards that apply to each entity, since those are not always stored in the descriptor. Ask the platform team to confirm that every owner reference resolves to an existing group or user. Done means an ownership and relationship table exists, with no orphaned references left unexplained.
Verify counts and fields against the source
Compare the archive with the inventory from step two. Check entity counts by kind (Component, API, Resource, System, Domain, Group, User, Template and Location) and by owner, then sample fields such as name, lifecycle, owner and tags for a set of entities that the team agrees on. Record every mismatch and its resolution. Done means the counts match for each kind and owner, and the sampled entities agree field by field, with the check results saved in the archive.
Keep a dated archive
Store the verified export, the inventory, the written answers from Roadie, the scope note and the check results in one dated, access-controlled location, and record who approved the archive. Keep a copy that is separate from the Roadie tenant, so the record survives after the contract ends. Done means the archive is complete, its contents are listed in an index file, and an approver has signed off on the final count comparison.

Which entities need a catalog-info.yaml written before you leave

Entities that were imported from a repository already have a descriptor file, usually named catalog-info.yaml, that Roadie reads through a Location or discovery setup. These files are portable because they follow the open Backstage descriptor format, so the same file can be read by a self-hosted Backstage instance without rewriting. The work here is verification rather than creation, and the goal is to confirm that Roadie's copy matches what is in Git.

Check the default branch: Confirm that the descriptor is merged to the default branch, since uncommitted or feature-branch edits will not reflect what the catalog actually shows.
Compare the owner field: Make sure spec.owner names a Group or User that exists in your identity source, not a label that only Roadie understood.
Confirm the kind and lifecycle: Check kind (for example Component, API or System) and spec.lifecycle against the entity as it appears in Roadie.
List Location targets: Record every repository or URL that Roadie scans, so the same discovery paths can be configured in your own instance.
Note annotations: Record annotations that link to CI, monitoring or docs, since these point to integrations you will need to re-create.

Review each descriptor against the Backstage descriptor format documentation before import, because a file that is stale or points to a missing owner will still load but show incorrect ownership.

Entities created through Roadie's interface exist only in the Roadie catalog, so they have no descriptor in any repository. Before the contract ends, each one must be written as a descriptor and committed somewhere your teams control. Without this step, the entity and its ownership are lost at cutover and must be rediscovered by hand.

Export the list: Use the catalog views in Roadie to list entities without a source location, and record name, kind, owner and tags for each.
Choose a home repository: Place each descriptor in the repository of the service it describes, or in a dedicated catalog repository for resources and groups that have no code.
Write the core fields: Set apiVersion, kind, metadata.name, spec.type, spec.owner and spec.lifecycle for each entity.
Add a Location for shared files: If you keep catalog files in a separate repository, register it with a Location entity so the importer can find it.
Assign a human owner: Every descriptor needs an owner that someone accountable can confirm, because an entity without one is hard to maintain after the move.

Re-read each new descriptor against the descriptor format documentation and confirm the kind is the one you intend before you commit it.

Why verification matters more than the export itself

An export is only useful when the target catalog matches the source, so the verification step decides whether the migration is finished. Compare entity counts by kind across Component, API, Resource, System, Domain, Group, User, Template and Location, using the same filters on both sides. Then check the fields that carry business meaning: each entity's owner, its lifecycle tag, its links to runbooks and dashboards, and the API definitions attached to API entities, whether OpenAPI, AsyncAPI, GraphQL or gRPC. A count that matches can still hide entities whose owners or relations were dropped, so sample entities from every team and compare them field by field. Keep a written record of the comparison so you can show what was checked and what was accepted as a known difference.

Ownership is the field most likely to break. Backstage's authentication documentation advises configuring sign-in resolvers so that every provider resolves to the same identity, and it advises against offering guest access in production. In practice, each owner reference in your exported catalog-info.yaml files must point to a Group or User entity that exists in the new portal and maps to a real person or team. Confirm how your identity provider names users and groups, since a mismatch between a Roadie-era identifier and the new sign-in identity leaves orphaned entities. Run the check on the production-style database, because Backstage uses PostgreSQL in production, and do not rely on a development setup with SQLite. Finally, build TechDocs from the exported Markdown and confirm that every documentation site renders, since a catalog can look complete while its docs are broken.

What to plan before the Roadie renewal or termination date

Catalog export is the technical step, but the contract sets the clock. The cards below cover the commercial, data and access decisions to settle with Roadie and your own legal or procurement team before the export starts, so ownership data is not lost at cutover.

Notice and renewal dates

Find the notice period, renewal date and auto-renewal terms in your Roadie order form or subscription agreement. Confirm with Roadie and your procurement team which date counts as the last day to give notice, and whether notice must be in writing and to whom. Work backward from that date to schedule the export and the parallel run.

Export deadline and read-only period

Ask Roadie whether access to the portal, the API and the catalog will change after the contract ends, including any read-only window and how long it lasts. Confirm whether exports are available in a self-service form or need a request. Record the exact cutoff so the export runs before access ends.

A named owner for each data type

Assign one person to each category: catalog entities, ownership and group data, scorecards, templates, TechDocs sources, integration settings and user access. Each owner confirms what is exported, what is recreated and what is dropped. Without named owners, scorecard definitions and custom metadata are the items most often missed.

Repository access and integration credentials

Inventory every token, app installation, webhook and service account that Roadie uses to read repositories, cloud accounts and other tools. Plan how each credential is rotated or revoked, and who issues the replacements for the new Backstage deployment. Confirm with Roadie that no credential is needed to keep catalog data readable during the export.

Parallel-run period in the new portal

Run your self-hosted Backstage portal alongside Roadie long enough to compare entity counts, ownership, relations and TechDocs output against the source. Agree the length of the parallel run in your project plan and the criteria that close it. Keep Roadie live until those checks pass, within the notice terms you confirmed.

Data retention and deletion after cutover

After cutover, ask Roadie in writing how long it retains your catalog, logs and user data, and request deletion with written confirmation. Ask your legal team whether any record must be kept for audit or contract reasons before deletion. Keep a copy of the exported data under your own retention policy.

What does a Roadie catalog export cost and take?

What drives the effort of exporting a Roadie catalog?

The effort scales with how many entities you have, how many of them exist only inside Roadie, and how much configuration sits around them. A catalog where most entities already live as catalog-info.yaml in repositories is mostly a verification exercise. A catalog built largely through the UI or API needs each entity read out, mapped to a descriptor file, and reviewed by its owner. Count entities by kind first, because Components, APIs, Systems, Groups and Users each carry different relations and ownership fields. Plugin-backed data such as scorecards, integration mappings and custom annotations adds a second layer of work, since those values must be re-declared in your own setup rather than copied across.

How much of an export can our own engineers do alone?

A team with Backstage experience can usually handle the repository side alone: confirming that catalog-info.yaml files are present, valid and owned by the right group. The harder parts are the entities that were never committed, the relations that depend on other entities, and the scorecard or plugin configuration that has no direct file equivalent. If nobody on the team has written Backstage descriptors or run a Backstage instance, the learning curve becomes the real cost. Ask yourself whether the people who know the catalog best have time in the next quarter to review each entity, because ownership data is only accurate when the owners themselves confirm it.

What do our platform and security teams need to provide?

Platform engineering owns the target: where the Backstage instance runs, how it is deployed, which PostgreSQL database backs it and how the catalog is loaded. Security owns the access model. Backstage's authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity, and not offering guest access in production, so security should review the identity provider integration before any user logs in. You also need an agreed process for who may read exported data, where export files are stored and how they are deleted after cutover. Both teams should sign off on the export inventory before the contract ends.

How long does a catalog export take?

The timeline depends on scope, and this page does not estimate it. The variables are the entity count, the share of entities created outside repositories, the number of plugins and integrations in use, the volume of TechDocs content and the skills available on your team. Any duration should come from a written scope that lists deliverables and dates before work starts, which is how DeployOpen engagements are normally agreed. Also check your Roadie notice and renewal dates, because the export window must close before access ends. Plan the export as a dated project with checkpoints, not as a single task at the end of the term.

What should we ask Roadie for before the contract ends?

Ask Roadie to confirm, in writing, the export options available on your plan, the format of the data, and how long read access remains after termination. Request a complete list of entity kinds, relations, annotations and owner assignments, plus any scorecard definitions, template configurations and integration settings you rely on. Ask how your TechDocs source content and search configuration can be retrieved, and confirm whether any data is held only in their systems. Keep a copy of the commercial terms that describe data return and deletion, because those terms decide what you can rely on later.

What should we ask an outside partner for in a quote?

Ask for a written scope that names the entity inventory method, the list of integrations and plugins in scope, the TechDocs and search work, and the cutover checks. Confirm who performs ownership review, who signs off on the inventory, and what evidence you receive at the end. Ask which items are fixed-scope deliverables and which are ongoing support or retainer work, because most DeployOpen engagements are fixed-scope and agreed in writing before work starts. Request the timeline as part of the scope document. DeployOpen does not publish a price list, so a quote follows from that written scope, and it should describe what is one-time (the export and migration) and what recurs (hosting, upgrades and support).

How DeployOpen works on this

DeployOpen treats the Roadie catalog exit as a fixed-scope piece of work: we inventory what Roadie holds, agree what moves and in what form, and then rebuild it on a Backstage portal inside your own infrastructure. Scope, deliverables and timelines are agreed in writing before any work starts.

How we scope

We inventory which entities exist only in Roadie's UI or API and which already live in catalog-info.yaml files.
We agree in writing which entity kinds, owners, relations and annotations the export must preserve.
We confirm with you which integrations, scorecards and users must be recreated, and who signs off each item.

How we build

We generate or update catalog-info.yaml files for UI-created entities and validate them against the descriptor format.
We test that imported entities resolve to the same owners and groups on the target Backstage instance.
We document each export script and mapping so your platform team can rerun or extend it after handover.

How we hand over

We deliver a written record of exported entities, unmapped items and open decisions, reviewed with your catalog owners.
We walk your platform engineers through the repositories, descriptor conventions and import process they will maintain.
We agree a closing checklist covering data retention, Roadie access removal and confirmation that no ownership data was lost.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the exit is complete.
Post-cutover fixes for descriptor drift or missed entities can be scoped as a separate fixed-scope piece of work.
Your team keeps ownership of the portal, and we confirm the support terms you want in the written scope before work begins.