Skip to main content

v1.31.0

These are the release notes for the v1.31.0 release of Backstage.

A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.

Highlights​

Backend System 1.0 🎉​

The time has come for releasing the new Backend System as stable version 1.0! This means that the API is now stable and breaking changes should not occur until version 2.0, see our package versioning policy for more information about this.

There is documentation in place both for migrating backends and migrating plugins, and we encourage you to start doing so as soon as possible. Going forward, we will increasingly refer to this as "The backend system", and the previous one as "The old backend system". The main Backstage and community-plugins repositories have already been more or less fully migrated over.

The backend system brings a host of improvements to the way that backends and their features are constructed. Instead of the old convention-based structure that could lead to migration pains, features now fit together with dependency injection like a jigsaw puzzle while leveraging powerful core services and extending each other dynamically with additional behaviors. And this is just scratching the surface of it - do check out the docs!

We are very excited about this important milestone after a long period of development and refinement together with our passionate community, and hope that you will find it as refreshing and simple yet powerful as it was envisioned to be. This also lays the foundation for us being able to continue iterating at a high pace without incurring undue end user breakages during upgrades.

Keep the feedback coming! Either on the Community Discord, or through issues on GitHub. Also if you’re looking for a way to help, please take a look at these backstage and community plugins issues about deprecating old-backend capabilities of already migrated plugins.

Technical details​

At a technical level, the following packages are now on major version 1, and their major version 0 will stop receiving feature updates:

  • @backstage/backend-app-api
  • @backstage/backend-plugin-api
  • @backstage/backend-test-utils

The following packages are deprecated and frozen (have stopped receiving updates). Please use the above three packages and @backstage/backend-defaults to replace them. You may still use the compatibility adapters in @backstage/backend-common short term while performing a gradual migration.

  • @backstage/backend-common
  • @backstage/backend-tasks

The following core services have been entirely removed. Please migrate to the new auth system.

  • coreServices.identity
  • coreServices.tokenManager

The backwards compatibility with plugins using legacy auth through the token manager service has also been removed. This means that instead of falling back to using the old token manager, requests towards plugins that don't support the new auth system will simply fail. Please make sure that all plugins in your deployment are hosted within a backend instance from the new backend system; a mixture of new and old will lead to auth problems.

For a lot more detail about what changed and what migration steps might be needed, check the release notes for versions 1.27, 1.28, 1.29 and 1.30.

New Frontend System Updates​

Some new things have landed in this version for the continued work on the New Frontend System. We’ve introduced the @backstage/plugin-app package, which is now responsible for housing the built in extensions and providing an entry point to override them using appPlugin.override().

There’s a new round of deprecations as we move forward with the New Frontend System. Namespace is no longer required to be provided to all extensions, or Blueprints and their respective .make or .makeWithOverrides methods. This will now default to the ID of the plugin that they are installed alongside.

We’ve deprecated createExtensionOverrides and introduced a new createFrontendModule method which replaces it and takes a required pluginId for which to associate the extensions that you’re providing to override or compliment the corresponding plugin.

We’ve also deprecated the createApp import from @backstage/frontend-app-api and you should now use the same import from @backstage/frontend-defaults instead which aligns nicely to the New Backend System patterns.

There’s more information on the above deprecations and migrations in the 1.31 migration docs

We’ve removed V1 extension support, so all extensions should now be defined with the array form of outputs, instead of the previously deprecated object form.

All previous extension creators that have the Blueprint equivalent have also been removed as they were previously deprecated. Instead of create<Kind>Extension you should migrate to using <Kind>Blueprint.make instead.

Also the deprecated .render method has been removed from createExtensionTester, you should be able to use renderInTestApp directly with the tester.reactElement() instead.

There’s also migration docs for the above removals from the last deprecation ICYMI!

Yarn v4 by Default​

When creating a new Backstage repository with @backstage/create-app, it will now be powered by Yarn version 4. There have been several improvements in later versions of Yarn, so this should improve the experience when getting started.

If you are still on version 1 in your pre-existing repository, there’s a guide for getting onto newer releases. At this point we recommend moving ahead with moving off of version 1 of Yarn.

Contributed by @awanlin in #26610

App Runtime Templating​

The @backstage/plugin-app-backend now supports injection of all parts of the frontend configuration at runtime, including the public path and configuration values that are templated into index.html.

The build process for frontend apps in the @backstage/cli now outputs an additional index.html.tmpl file. If this file is present in the build, the app backend will use this file to template a new index.html using the configuration that’s present in the app backend. This change also switches the full frontend configuration to be injected directly into the index.html file inside a script tag, rather than deep in the static resources.

Guest auth no longer halting production startup​

The @backstage/plugin-auth-backend-module-guest-provider module will no longer cause the backend to fail to start up in production, it now instead refuses authentication attempts. The halting of the startup could lead to knock-on effects such as migration tables staying locked.

New Catalog Permissions​

The analyze-location endpoint of the catalog is now protected by the catalog.location.analyze permission, and the validate-entity endpoint is now protected by the catalog.entity.validate permission. If you have enabled the permissions system, you may want to adjust your policy accordingly.

Contributed by @04kash in #25924

GitLab Provider​

The GitLab org entity provider now has a new relations configuration option that controls how GitLab memberships are modeled in Backstage. As part of this change the existing allowInherited option has been deprecated as it can now be expressed as relations: [INHERITED].

Contributed by @elaine-mattos in #25363

Star Icon Overrides​

Allow custom star icons to be provided via the star and unstarred icon overrides. See how to override existing icons in the Backstage documentation.

Migrated Auth Providers​

The last two backend auth providers - Auth0 and BitBucket Server - were migrated to new backend modules, closing the big community effort in getting the auth providers migration done.

Thanks again to everyone who helped out, it is greatly appreciated!

Catalog Client Performance Improvements​

A hotspot was found in the code, where calls to the catalog backend to fetch entities performed work on the client side that were better done on the server side. After this update, you may see significant reduction in CPU usage on callers that fetch large amounts of data from the catalog.

Contributed by @drodil in #26240

New Catalog Service Mocks​

When testing features that interact with the catalog, it’s common to want to inject a mocked or faked catalog client. To make life simpler, we’ve added a catalogServiceMock to @backstage/plugin-catalog-node/testUtils. Just like many of the mockServices from the test backend utilities, it lets you create partial mocks to make assertions on, as well as entire fake catalogs pre-populated with a static set of entities. Check it out!

Scaffolder Fixes​

Added support for liveOmit and omitExtraData options to the form which will allow for trimming superfluous data from the resulting data collected from the user. We will be testing this one for this release and promote this as the default if all goes to plan for the next mainline release. Thanks @jboeijenga!

@stepghenglass has been on a roll, and contributed a bunch of fixes for the Scaffolder and the SecretField. It now supports being disabled, required and maxLength and minLength being set from the schema. They’ve also contributed some fixes for the ReviewState component, to correctly parse the ui:backstage options for nested fields in the parameters schema. Thanks to @richcooper95 for some other improvements to that component too and making it look much better when you have nested properties in the summary 💅.

Security Fixes​

  • Fix in the Catalog backend where a vulnerability could be exploited to disrupt the backend instance availability.
  • A fix for a vulnerability in the TechDocs backend that could allow unauthorized access to TechDocs content when hosting the content externally.
  • A fix for a vulnerability in the TechDocs backend that could allow authenticated users to bypass script injection protections.

Upgrade path​

We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for keeping Backstage updated.

Below you can find a list of links and references to help you learn about and start using this new release.

Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.