Thanks to this week’s releases, you’re now using the latest version of Backstage (1.3), you can choose the default kind displayed in the Catalog, you get twice as fast page loads, you won’t experience broken mkdocs links, and you can learn best practices to model your users and groups.

You’re running on the latest Backstage!

All Roadie customers are now using on Backstage 1.3! However, we’ve pinned the Scaffolder as to prevent any disruption to existing templates. We’ll be taking a closer look at compatibility these weeks.

New feature: Customise your Catalog’s default kind

Before, every time you opened the Catalog, you’d see a list of Components by default. Now, you can customise the kind of entities that you see listed as default, whether they’re Systems, APIs, or anything else.

To set the default kind for your Catalog, head to Administration > Setting > Catalog > Default Kind.

UX Improvement: Doubled page load speed

You may have already noticed this: Backstage now loads noticeably faster. We optimised our delivery strategy to reduce the page load time by 50%. We continue to work on improving our UI’s performance.

Fix: Broken mkdocs edit link

If you had set your main mkdocs file to something other than index.md, your edit button would take you to the wrong location. We fixed this error upstream in Backstage and it’s also available for all Roadie customers.

Heads up: if your existing Edit link disappears, you’ll need to add a repo_url to your mkdocs.yaml file.

Documentation: Modelling Users and Groups

We’ve put together best-practices for modelling your organisation’s teams and people to represent ownership in Backstage. We include instructions for doing so via Github Teams or manually through YAML. Check out the documentation.

This week, we finished upgrading all Roadie’s customers to Backstage 1.1.0, updated plantuml, and released quite a few UX improvements.

All Roadie’s tenants have been upgraded to 1.1.0

Upgrading Backstage is one of the most challenging points of adopting Backstage. We’ve heard reports from self-hosted teams spending up to 30% of their efforts managing upgrades.

In this upgrade, our engineers had to deal with breaking changes in core components such as authentication, Kubernetes, and permissions.

Thankfully, as a Roadie customer, you get the upgrades managed for you. All features, no pain!

Updated Plantuml

We updated the plantuml extension for mkdocs. You can now make use of more recent plant uml features in your TechDocs.

UX improvements of the week:

1. Filtering by kind (i.e. component, API, domain, etc.) was confusing for new users because the input had inconsistent styling. We’ve styled the kind filter to be in line with the rest of the filters.
2. Filtering by name used to only filter by metadata.name, but the UI displayed metadata.title, leading to confusing outcomes. Now, the filter consider both fields into account.
3. Sidebars didn’t allow editing, so teams would have to remove and re-add elements if they wanted a change, which could be frustrating. Now, sidebars allow editing their content.
4. The Intercom prompt would sit on top of other UI elements in a few scenarios, obstructing the user from using them. Now, the ‘Talk to us’ button is the last item of the sidebar menu.

This week, we’re releasing two Roadie exclusive features to make it easier to register and update entities and adding a small UX improvement.

Roadie exclusive feature: Entity Previews

At the moment, Backstage isn’t very friendly when it comes to changing your catalog-info.yaml: any modification causes a full override of the current entity state. Thus, you want to make sure your catalog-info renders the right information, and do so without much repetitive work. That’s why we’re excited to introduce Entity Previews to all Roadie’s customers:

With Entity Previews, you can write a catalog-info.yaml file on the spot, validate it, and launch a preview entity. If your catalog-info is good to go, you’ll find a fully formed entity page preview to check if it looks as you expect. Otherwise, you’ll see what went wrong.

You can find the new feature under Administration > Tools > Entity Preview. Learn more about this feature in our documentation.

Roadie exclusive feature: Entity Status

After a change, it can be hard to tell if an entity is still loading or if an error occurred when ingesting or updating it. We’ve introduced error statuses to the entity card to provide you with immediate feedback without having to dig through the locations log and the entity inspector. As a Roadie customer, you get this feature automatically!

Improvement: Custom fields saved on blur

When editing custom props in a component, the UI required you to click a dedicated save prop button before saving the component’s changes. This was confusing and would sometime lead to unsaved props work. Now, we’ve made it so props are saved automatically to prevent this from happening.

We’ve been focussed on added debugging tools to Roadie Backstage so you can figure out why things are not working as you expect.

This theme is an ongoing priority at Roadie, so you should see even more stuff like this next week.

Template previewing tools (feature)

We’ve reorganized the tabs in the administration area to ensure that the most widely useful pages are easiest to access. We’ve also added a new Tools tab.

Inside the Tools tab, you’ll find the old versions page — which is useful to folks who are building custom Backstage plugins — along with a new Template Previewer.

As the name suggests, the template previewer lets you preview scaffolder templates in real time, so you can see what the resulting UI will look like.

This feature was contributed upstream by the prolific Phil Kuang. Here’s the PR. We’re just exposing it.

Phil included this nice demo video which gets the idea across.

We’ll be expanding this TOOLS tab with more catalog debugging tools soon. Watch this space.

Stuck checks (bugfix)

In a small number of very specific repos, some customers experienced issues where Roadie pull request checks were blocking PRs which have nothing to do with Roadie.

We now only add roadie validator checks where a backstage related file has changed. Previously, we added a skipped check.

New Roadie logo

The new Roadie logo has rolled out to all Roadie Backstage instances. You’ll notice a change in the favicon and the sidebar.

We feel this is appropriate now since we are soon beginning work on our first major proprietary features on top of Backstage.

We still do plan to eventually allow you to replace these logos with your own branding. Although I don’t have an ETA for that feature at this time.

Self-service Auto-discovery

Auto-discovery enables Backstage to automatically look in named locations for catalog-info.yaml files.

We’ve always supported auto-discovery, but the configuration was not exposed to Roadie Backstage admins until this release. You can now turn auto-discovery on and off and edit the glob used for finding the catalog-info files.

Our documentation has detailed information explaining how to get the most from this interface.

Login prompt on settings page

Previously, Roadie hid the settings area from non-admins completely. Users who visited this area would only see Versions and Locations.

This turned out to be confusing, and admins would frequently report that they had lost the ability to see the settings. The cause was usually just that they were not logged into GitHub, which meant that the application couldn’t tell if they had the correct permissions to see the settings.

To help with this issue, we now display the settings to everyone, and prompt people to log into GitHub as a reminder.

Once logged in, we can check if the user actually has the permissions to see the settings or not.

Changelog RSS feed

You can now add the Roadie changelog to your Roadie Backstage Home.

This works via the HomePageRSS card which is now available in Roadie Backstage. This can be used to render any RSS feed, but we like to use the following props configuration to render this very Roadie Changelog.

{
  "feedURL": "/api/proxy/roadie-changelog"
}

catalog:register Scaffolder action

You can now use the catalog:register step in your scaffolder templates. It allows the software template to configure the creation of a new catalog item in the Backstage catalog.

We’ve been focussed on small UX improvements and Bugfixes for the past week or two so the changes are coming thick and fast. Expect more of the same for the next few weeks.

New logo

Roadie has a new logo! Within a week, this will replace the Backstage logos found in the application. You may want to warn your teams so they are not surprised.

We are beginning our first major initiatives which will add extra non-Backstage features to Backstage, so we feel it is appropriate to start owning the brand a bit more.

We still plan to allow you to upload your own logos.

Catalog troubleshooting guide (docs)

Debugging catalog ingestion problems isn’t always easy. To help you and your end users, we’ve written a comprehensive troubleshooting guide.

It explains how to use the Locations Log to track down problems and how to deal with common errors.

Scaffolder template creation guide (docs)

This new guide covers the syntax and options available when writing scaffolder templates. Every available action is covered, along with explanations of the arguments they take.

There’s also a troubleshooting section we will build on to cover common problems.

Placeholder secrets (enhancement)

Sometimes you want to make an authenticated HTTP request to a third-party service as part of a scaffolder template or a frontend plugin. We’ve added a few placeholder secrets to the secrets page so you can do this.

At some point we’ll make this page fully dynamic so you can create your own named secrets.

You can read about how to setup a proxy with these tokens in this guide.

Link to docs from the sidebar (enhancement)

You can now link directly to individual TechDocs documents from the sidebar inside Roadie. Previously this would break the application routing.

Prevent duplicate custom plugin cards (bugfix)

It was too easy to accidentally save empty and duplicate custom plugins in Roadie. This caused confusion for users who were writing their own plugins. This is now fixed.

Adding the catalog to the sidebar should not break the app (bugfix)

Adding a link to the catalog into the sidebar would previously render a broken white page for the user. It would also break the Home widget. This should no longer cause a problem.

Shortcut home page widget (feature)

We’re big fans of project management application Shortcut at Roadie. For our own day to day usage, we made a home page widget which shows the tickets currently assigned to the logged in user.

This is currently undocumented but if you’ve added a plugin previously it should be self-evident.

This week we have 3 significant user facing improvements.

Multiple tech radar support

We heard from a couple of customers that they need multiple tech radars because they have independent hardware and software divisions or different orgs with different needs.

You can now add multiple instances of the Tech Radar plugin to the sidebar in Roadie Backstage, and configure them independently. Each configuration now takes an ID, which can then be associated with an instance of the plugin.

The docs have been updated with more in-depth instructions.

Header bar theming

You can now set the main header inside Roadie Backstage to an arbitrary color. Perhaps to match a specific brand your company has.

It’s easy to do, just paste a hex color code into the input on the Theme Customization settings page.

Here’s a blinding organge look… 😀

Generic iframe embed component

We’ve added a widget which can be used to render content into a generic iframe. In the screenshot below, I’m using it to embed an Introduction to Backstage video on the Home page. You might use it to display charts, data or whatever else you need.

It required a few simple properties to set up. The docs are here.

The next improvement we make to this will allow the source URL to be configurable on a per component basis, rather than per component type, which is how it works now. This should make it more useful on the component pages, where you want to display different information for each component.

Azure Plugin

This week we have added support for the Azure DevOps service.

It supports builds and azure repos. For more information on how to get this working for you, please visit this link.

Page load performance improvements

We have improved caching in the Roadie app in order to:

• Removed 50+ extra requests to our backend to fetch static js/css/html files
• Improved the load time of the catalog page from < 10 seconds to just below 2 seconds!

These are the user facing improvements we’ve shipped in the past week.

Home cards for GitHub

We’ve released two new cards for the Backstage Home page. They show you your GitHub Pull Requests and Review requests.

To use them, add the HomePageRequestedReviewsCard and HomePageYourOpenPullRequestsCard cards to your Home page.

Here’s how they look:

Allure plugin

The Allure plugin is now available for all Roadie Backstage users. It can display the Allure reports of the components in your Roadie Backstage catalog.

To use it, follow the three simple steps in our docs.

Session refreshing bug 🐞

We’ve fixed a tricky session refreshing bug which has been reported a few times over the past few weeks. This would cause the Refresh Session dialog to be displayed over and over even after clicking the “Refresh” button. This is now fixed and the session will refresh as expected when the button clicks.

Backstage 1.0 is here, along with the new Google Calendar home page. We now support Bitbucket and we have a new docs site.

Backstage 1.0

This week we upgraded all Backstage instances to the 1.0 version of Backstage. You can read the official blog post to learn more about what this means for Backstage. The full release notes are here.

Google Calendar homepage plugin

One cool feature from this release is The Google Calendar home page widget. It lets you check your upcoming calendar events on the Backstage home page.

If you want to use it, check out the docs.

Bitbucket support

You can now connect Roadie to Bitbucket in Administration -> Settings -> Integrations and start importing catalog files from Bitbucket. The scaffolder is also supported so you can create Bitbucket repos from Roadie too.

The docs are here.

Refreshed Roadie docs

Speaking of docs, we’ve also launched a redesigned documentation site at https://roadie.io/docs/. As we’ve grown and added more features to Roadie, we’ve found our old docs structure struggled to keep up.

The new docs layout uses tabs to organize the main documentation sections. It also features a brand new plugins and integrations database so you can easily see which plugins Roadie suports.

We made it easier for Roadie admins to remember how to make other users admins by adding an explanation and a shortcut to the admin group under Administration -> User Management page.

We have added support for mermaid syntax in techdocs. If you would like to use mermaid diagrams, you can add the markdown_inline_mermaid extension.

site_name: 'mermaid-demo'
site_description: 'Mermaid Demo'
markdown_extensions:
  - markdown_inline_mermaid
nav:
  - Index: 'index.md'

Then in your markdown docs you can add a mermaid diagram.

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

You can read more about the mermaid syntax here: https://mermaid-js.github.io/mermaid/#/

Today sees support added for 3 more Backstage plugins. Also, TechDocs requires a little less boilerplate than before.

The TechDocs core plugin is now optional
You no longer need to manually add the techdocs-core plugin to every mkdocs.yml file.

Omitting the techdocs-core plugin would make some docs looked quite broken inside Backstage. We’ve seen a few instances where Roadie users have been confused because they forgot to list it in their MkDocs configuration.

This change, contributed by Roadie engineer Jussi Hallila, should reduce the friction for teams who are adopting TechDocs. This is live on Roadie Backstage now.

Lighthouse plugin
Lighthouse is a website performance testing tool from Google. It has a Backstage plugin which adds a lighthouse UI and displays performance test results for websites inside your Backstage catalog.

The lighthouse plugin is now supported on Roadie Backstage.

You’ll need to run your own lighthouse audit service instance to use it. Once you do it should be easy to point the frontend in Roadie at that service, so you get the full integrated experience. This even works behind a VPN.

Documentation explaining how to use the lighthouse plugin on Roadie is here.

Jenkins plugin
Jenkins is one of the most popular CI runners in the world. The Jenkins plugin for Backstage allows you to see CI results inside Backstage alongside all of your other service information.

The Jenkins plugin is now supported on Roadie Backstage. The integration docs are here.

Grafana plugin
Grafana is an open-source (and hosted) ovservability platform. It provides “Operational dashboards for your data here, there, or anywhere.”

The Grafana plugin is now supported on Roadie Backstage. The integration docs are here.

Roadie now allows admin users to select columns they want to see displayed in the catalog page.

This can be configured under Settings -> Configuration -> Catalog. Just choose which columns you would like to see and remember to click “Save”.

All Roadie Backstage instances have been upgraded to Release v0.71.0.

Some of the user facing features and changes include:

• The AboutCard has been removed and replaced with EntityAboutCard. We transparently handled this migration for all of our users.
• Support for backstage.io/v1beta2 scaffolder templates was removed.
• Markdown can now be used in the description of scaffolder templates.

The full upstream release notes are here.

The Roadie Backstage experience is slightly improved on mobile due to the addition of a new mobile drawer. The new feature makes the search, sidebar menu and account page more accessible on mobile.

See the black bar at the bottom of the page in the screenshot below.

There’s lots of work still to do in order to have a fully functional Backstage experience on Mobile, but this is at least one step in the right direction.

Card widgets from Backstage plugins sometimes provide a poor experience to viewers when the annotation they need is missing. We’ve fixed this.

Adding a card — like the Pagerduty card shown below — to the entity page of components of type “service”, causes that card to be added to all services in the catalog.

It’s likely that some services in the catalog won’t have the PagerDuty annotation set. Often for legitimate reasons. They might be experimental services with no operational load and no need for PagerDuty.

When the annotation wasn’t set on a service, Roadie Backstage would display an ugly red error message to anybody who viewed that service in the catalog. This behavior was discouraging people from using the cards as intended.

From now on, we will hide these cards from the interface so that users don’t see this ugly error.

It’s important to inform users that it might be a good idea to add the PagerDuty annotation to their service. To do this, we’ve added an “eye” icon to the admin controls area of each service which is potentially missing an annotation.

Clicking the eye will inform the user about the annotations they might want to add.

We’ve also added some documentation to help people learn about all of the annotations available, and the plugins which use them.

All Backstage instances have been upgraded to Release v0.69.0.

There are no major new features to be aware of.

There were approximately 26 breaking changes throughout the codebase in this relesase.

The upstream release notes are here: https://github.com/backstage/backstage/releases/tag/v0.69.0

We have added support for the Cortex plugin in Roadie Backstage.

This plugin has three components which you can add to your sidebar, tabs and component dashboards.

We have published docs which explain how to use the plugin here.

We have released a new version of Backstage, which includes the new inspect entity function.

The changelog is here.