Decorators for rich Team pages

Today we released a feature we call Decorators. Decorators allow you to easily add metadata to the stuff you track in your Roadie Backstage catalog. This metadata is stored within Roadie, and not written to YAML.

How to use Decorators

Using Decorators is simple:

1. Visit an Entity in your Roadie Backstage catalog (e.g. a team, service or system).
2. Click the three dots in the top right corner and click “Decorate entity”.
3. Add links or annotations to the Entity and press Save.

Decorators you create are stored inside Roadie and not written back to the YAML file that backs the Entity.

This means that Entity metadata can come from multiple places for the same Entity. One annotation could come from YAML, and another from Decorators.

You can see where a specific piece of metadata is backed off to by clicking the three dots again and clicking “Inspect entity”. In this case below, the backstage.io/source-location is internal to Backstage and the other items are applied by Roadie Decorators.

Why we’re doing this

The introduction of Decorators is a slight deviation from the Backstage way of doing things, so it’s important that we explain why we’re doing this.

Auto-ingested sources need decoration

Backstage implementations frequently source the hierarchy of Users and Groups from a tool like GitHub Teams, Okta, or a Human Resources application like BambooHR. To support this, Backstage has a number of integrations into these tools.

These integrations will typically stream the hierarchy of Users and Groups into the Backstage catalog.

The problem with automatically ingesting Users and Groups is that Backstage users don’t get a chance to enrich their Group with information like links to Slack channels or a team charter. This leads to dead looking Group pages in Backstage.

Decorators give Backstage users a way to enrich their Group with the information that they want to show-off.

What this is not

We’re not introducing anything brand new in the Backstage ecosystem and we’re not introducing vendor lock-in.

There’s precedent

Backstage itself adds internal annotations to each Entity. These annotations are not written back to the YAML files. They are instead stored inside the Backstage database.

You can see some examples of this internal metadata here:

Roadie is simply piggybacking on this mechanism, to add the ability to store links and annotations.

We’re Backstage API compatible

We’re not introducing any Roadie-specific changes to the Backstage API or the spec for Backstage YAML files. We’re just making it easier to add values to the existing spec.

Entity Decorations are available via the standard Backstage HTTP API that we expose, so you can always write them back to YAML if you wish.

In the future, we will look to support “exporting” Decorators into any YAML file that backs the entity.