Skip to main content
Import your Backstage software catalog into incident.io, bringing components, systems, APIs, and the groups that own them into Catalog. Ownership and dependency data arrives with the entities, so you can route an escalation to the group that owns a failing component and see what else depends on it. Backstage syncs through the catalog importer, our CLI for bringing catalog data in from any source. It ships with a Backstage template that creates the types below and keeps them current, which is the place to go once you’re ready to set it up.

​
What gets imported

The Backstage template creates eleven catalog types, each mapping to a Backstage kind or one of its enum fields. These are a starting point rather than a fixed list. Each type is defined in the template’s config, so you can add other Backstage kinds, drop the ones you don’t want, and pull metadata out of your own annotations.

​
Ownership and dependencies

Entities keep their relationships to one another, so the graph you have in Backstage is the graph you get in incident.io:
  • Components: link to the group that owns them, the system they belong to, the components they depend on, and the APIs they provide and consume
  • Systems: link to their owning group and their domain
  • Groups: link to their parent group, so your team hierarchy comes across intact
  • Users: link to the groups they belong to, and to their incident.io user by email address
Use these attributes anywhere Catalog is available, including routing alerts to teams, workflows, and custom fields. Two of them connect Backstage to the rest of incident.io:
  • Escalation path: the Backstage Group type carries an escalation path attribute that the importer creates but leaves for you to fill in. Set it against each group, and alerts routed to that group reach whoever is on call for it.
  • incident.io User: Backstage users are matched to incident.io accounts on their profile email, so the person who owns a service resolves to someone you can page. See connected users.

​
How the sync works

The importer reads your Backstage entities and writes them into Catalog. It can pull directly from the Backstage API, read catalog-info.yaml files from GitHub or from a repository checkout, or take the output of a script that assembles the data for you. Most teams run it from CI, either on merge or on a schedule, so the catalog tracks Backstage as it changes. A sync removes entries that are no longer present in your source, which is what keeps the two in step. Once a type is managed by the importer, incident.io links it back to the repository holding your config and stops it being edited in the dashboard, so your repo stays the source of truth. This works the same way as managing types in GitHub.

​
Set it up

Setup, configuration, and CI examples are maintained alongside the tool itself:

Backstage template

Install the importer and run your first sync

Sources

Connect to the Backstage API, including endpoints and auth

Outputs

Change which entities and attributes you import

Deploying

Run the sync from CircleCI, GitHub Actions, or GitLab CI

​
FAQs

Yes. Roadie-hosted Backstage needs a different endpoint and an unsigned token. See Sources.
Types managed by the importer are owned by your config, so the dashboard links to your repository instead of letting you edit them. Change the config and run a sync.
A sync removes entries that are no longer present in your source, which is what keeps the catalog matching Backstage. The importer has a dry run mode to preview changes first.
No. Each kind is a separate output in the template’s config, so remove the ones you don’t want or filter them out at the source.
Yes. Outputs select entities with a filter that runs against the raw entity, so any Backstage kind works, including your own custom ones.
The Backstage User type maps the profile email to an incident.io user, so anyone whose Backstage email matches their incident.io account is linked automatically. See connected users.