Update the Backstage catalog instantly without touching any YAML

Updating an entity in the Backstage catalog generally means manually updating a YAML file in a repository somewhere and getting it merged to the main branch.

For many, this manual process can feel like a series of hurdles—switching contexts, waiting for pull request reviews, and depending on other team members or systems.

This friction increases significantly when you scale across hundreds or thousands of repositories. For example, changing a group name might require chasing after numerous teams to raise and merge PRs, turning what should be a simple update into a months-long process.

Having to edit YAML makes keeping your catalog up-to-date a challenge, let alone enriching it with additional data or plugins like PagerDuty.

How long does it take to add a PagerDuty plugin?

Lets use the PagerDuty plugin as an example. Suppose you want to add PagerDuty monitoring to a Backstage entity representing a backend service. All you need to do is add an annotation to the YAML file with the relevant service ID.

The quickest way to edit the YAML file might seem simple: open GitHub, click the pencil icon on the About card, and start editing.

Manual Process in GitHub

Once inside GitHub’s web editor, you can make the change, commit it to a new branch, and open a pull request.

Sounds straightforward, right? But here’s where it gets tricky. To add the PagerDuty plugin, you need the correct service ID, which requires logging into PagerDuty, searching for the service that matches your entity, and then copying the ID from the browser’s address bar (since it’s not easily accessible in the UI).

In GitHub’s case, we can edit this immediately, commit it to a new branch and open a pull request rather quickly all in the web editor.

But to find the correct Service ID we must first go to PagerDuty. Hopefully we can log in and access the available services, and then search for the correct one using the names in the Component YAML.

Now, after locating the ID (in the address bar) and adding it to the YAML file, you still need to commit the changes, submit a PR, and wait for it to be reviewed and merged. Depending on the team’s review cadence, this could take days or longer.

Multiply this by hundreds of teams and thousands of repositories, and the process becomes incredibly slow and frustrating. Minor updates can take weeks or months to implement at scale.

A Better Way: Entity Updates with Roadie

At Roadie we’ve built UI based tools that allow you to set things like PagerDuty annotations with a few clicks. Instead of seeing a missing annotation card you’ll be able to select from a list of PagerDuty services and update the entity immediately, all from the same page in the UI.

Bulk updates via UI

But what if you need to update multiple entities at once? Roadie also provides a bulk editor that allows you to make updates across many entities using a simple table format. This dramatically reduces the manual effort required to keep your catalog accurate and up-to-date.

Behind the Scenes: How It Works

Our UI-based editors are powered by a backend feature we call Fragments. Fragments are partial entity data stored in a database table and merged into the existing entities in the catalog by a processor. These fragments can be updated through our UI or via API.

Leverage external APIs to make things easier

The custom UI we’ve seen earlier in this post also leverages external API’s to provide a dropdown of available options.

In this example we’ve used PagerDuty’s API to fetch a list of services using the API token already added to Backstage to make your PagerDuty plugin work. This call is made via the Backstage proxy which is set up to point to PagerDuty using your API Token on the backend.

Script bulk changes via API

However, sometimes bulk editing of metadata in the catalog is best scripted, and in this scenario, Roadie users make use of our Fragments API to make changes to entities, such as changing the ownership of a group’s entities when the group gets absorbed into another group, or updating any relationship references to a user entity when that individual leaves and someone else takes their role.

We’re not the only ones who’ve done something like this - companies like Twilio and others have built similar fragment functionality so that they can script updates to there catalog via API and free up platform teams to help keep the catalog data rich and accurate.

Reach out to us on Discord or our website’s chat messenger if you want to hear more about this and other improvements Roadie has made to the Backstage experience.