Merge pull request #25287 from backstage/1.28-release-notes

Release Notes v1.28

.github/vale/config/vocabularies/Backstage/accept.txt

@@ -161,6 +161,7 @@ hoc
 horizontalpodautoscalers
 Hostname
 hotspots
+howto
 http
 https
 Iain
@@ -291,6 +292,7 @@ Periskop
 permissioned
 permissioning
 pipx
+plaintext
 plantuml
 Platformize
 Podman

docs/releases/v1.28.0.md

@@ -0,0 +1,202 @@
+---
+id: v1.28.0
+title: v1.28.0
+description: Backstage Release v1.28.0
+---
+
+These are the release notes for the v1.28.0 release of [Backstage](https://backstage.io/).
+
+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
+
+### **BREAKING**: Proxy backend plugin protected by default
+
+The proxy backend plugin is now protected by Backstage auth, by default. Unless specifically configured (see below), all proxy endpoints will reject requests immediately unless a valid Backstage user or service token is passed along with the request. This aligns the proxy with how other Backstage backends behave out of the box, and serves to protect your upstreams from unauthorized access.
+
+Here's an example of how to configure:
+
+```diff
+  proxy:
+    endpoints:
+      '/pagerduty':
+        target: https://api.pagerduty.com
++       credentials: require
+        headers:
+          Authorization: Token token=${PAGERDUTY_TOKEN}
+```
+
+There are three `credentials` settings:
+
+- `require`: Callers need Backstage credentials. These are not forwarded to the target.
+- `forward`: Callers need Backstage credentials, which are forwarded to the target.
+- `dangerously-allow-unauthenticated`: No Backstage credentials needed. Target can apply its own checks. Incoming tokens of any sort will be allowed but ignored, and will also be forwarded if `allowedHeaders: ['Authorization']` is included.
+
+The new default is `require`, replacing the old `dangerously-allow-unauthenticated`. This means some previously permitted requests may now result in `401 Unauthorized` responses. This does not apply if `backend.auth.dangerouslyDisableDefaultAuthPolicy` is set to `true`.
+
+For proxy endpoints still requiring unauthenticated access, add `credentials: dangerously-allow-unauthenticated` in your app-config.
+
+See [the proxy documentation](https://backstage.io/docs/plugins/proxying/) for more information.
+
+### **BREAKING**: Gerrit integration breaking changes
+
+- The `workdir` argument have been removed from The `GerritUrlReader` constructor;
+- The Gerrit `readTree` implementation will now only use the Gitiles api, so the support for using git to clone the repo has been removed;
+- The `gitilesBaseUrl` is now mandatory for the Gerrit integration and the ability to override this requirement using the `DISABLE_GERRIT_GITILES_REQUIREMENT` environment variable has been removed.
+
+Contributed by [@anicke](https://github.com/anicke) in [#25123](https://github.com/backstage/backstage/pull/25123).
+
+### **BREAKING**: Github integration breaking changes
+
+- Removed deprecated code from when casing was changed from `GitHub` to `Github` nearly two years ago. The following items have been removed:
+  - `getGitHubFileFetchUrl` (use `getGithubFileFetchUrl` instead)
+  - `GitHubIntegrationConfig` (use `GithubIntegrationConfig` instead)
+  - `GitHubIntegration` (use `GithubIntegration` instead)
+  - `readGitHubIntegrationConfig` (use `readGithubIntegrationConfig` instead)
+  - `readGitHubIntegrationConfigs` (use `readGithubIntegrationConfigs` instead)
+  - `replaceGitHubUrlType` (use `replaceGithubUrlType` instead)
+
+Contributed by [@awanlin](https://github.com/awanlin) in [#25100](https://github.com/backstage/backstage/pull/25100).
+
+### **BREAKING**: OAuth Scope Updates
+
+The way that OAuth-based auth providers handle scopes has received several updates. There is now a new `.additionalScopes` configuration for all OAuth providers, which can be used to request additional scopes for all sessions. Many providers already had a similar configuration, but in most cases this did not work correctly as scopes requested by the client would override the configured set.
+
+Many providers now also have a set of required scopes that will always be present. This is in contrast to the previous solution where the client would be responsible for including a set of baseline scopes.
+
+A bug has also been fixed in the handling of persistent scopes, which could break session refresh for some providers, such as GitHub.
+
+### **BREAKING**: User Info service
+
+Limited-access user tokens (as used in cookies) no longer contain the `ent` ownership claim. This is notably used by TechDocs and the app-backend. If you use those services, you may want to log out and in again.
+
+Background: As part of the previous auth improvements, we added the `coreServices.userInfo` service. This service can extract user details from incoming credentials - notably the so-called `ent` claim with its ownership information.
+
+In this release, the auth backend part of this has been implemented, such that the information returned by your sign-in resolver gets persisted and can be acquired after the fact. With this in place, we could finally start slimming down on token sizes, starting with the cookie tokens. Unfortunately this has to be done in such a way that it’s breaking in the short term.
+
+If any issues persist, try clearing your cookies, and then reach out to us on Discord or with an issue if necessary.
+
+Contributed by [@kuangp](https://github.com/kuangp) in [#24729](https://github.com/backstage/backstage/pull/24729).
+
+### New Backend System API movement towards 1.0 release
+
+As part of finalizing the [New Backend System](https://backstage.io/docs/backend-system/), we are restructuring the out-of-the-box functionality a bit. As part of this release, you will see a large amount of deprecations on the `@backstage/backend-common` package (which will be deleted in a future release), and also on the `@backstage/backend-app-api` package (which is just being slimmed down to its essentials). Instead, you will see that the `@backstage/backend-defaults` package has received new subpath exports that neatly arrange all of these factories and default implementations.
+
+As an example, the `rootLoggerServiceFactory` export on `@backstage/backend-app-api` has been deprecated, and should now be imported from `@backstage/backend-defaults/rootLogger`. Most other deprecations follow the same pattern. Each deprecated symbol should have a deprecation message on it, which clearly states from where you should now be importing that particular functionality instead.
+
+This rearrangement was one of the crucial final pieces for settling the API surfaces of this backend system! We hope you’ll find it neater and clearer to understand.
+
+Please update deprecated imports in your own repo code as soon as convenient, to avoid the breaking changes in future releases when these symbols are finally removed.
+
+You will also note that backend features (plugins and modules) no longer are returned as functions, which simplifies interacting with features! You may see this in your editor in the form of deprecations, whose message tells you to remove the trailing parentheses.
+
+Your code may be changed in the following way as an example:
+
+```diff
+ await startTestBackend({
+   features: [
+     // service - stays unchanged
+     eventsServiceFactory(),
+     // module - remove parentheses
+-    catalogModuleBitbucketCloudEntityProvider(),
++    catalogModuleBitbucketCloudEntityProvider,
+```
+
+In related news, we have unified some type names. The `UrlReader` types are now properly prefixed with the service name, so you’ll see that for example `ReadTreeOptions` is now `UrlReaderServiceReadTreeOptions`. Functions better follow the proper naming convention for their arguments, for example `BackendPluginConfig` now becoming `CreateBackendPluginOptions`.
+
+### Package Metadata - Important for Package Publishers!
+
+All `@backstage/*` packages now include a new set of metadata in `package.json` that helps associate related plugin packages with each other. This metadata is also required for all packages published through the `@backstage/cli` to the Backstage ecosystem. For this purpose, a new `--publish` flag has been added to the `repo fix` command. You can read more about this requirement and how to generate the metadata in the documentation section on [Metadata for Published Packages](https://backstage.io/docs/tooling/package-metadata#metadata-for-published-packages).
+
+### Other Auth Improvements
+
+The OneLogin auth implementation now lives in its own module, `@backstage/plugin-auth-backend-module-onelogin-provider`.
+
+In some special use cases such as when you have read-replica databases, you may desire to not use the builtin zero-config plugin-to-plugin auth system that stores keys in the database. For those cases, there is now a new static mode where you supply key pairs in config that are used for this purpose. The howto is [in the docs](https://backstage.io/docs/auth/service-to-service-auth#static-keys-for-plugin-to-plugin-auth).
+
+There is also a new general `jwks` external access method for those of you who want to externally call Backstage plugins using already-established token flows! Check out [the docs](https://backstage.io/docs/auth/service-to-service-auth#jwks-token-auth).
+
+Contributed by [@ryan-hanchett](https://github.com/ryan-hanchett) in [#24681](https://github.com/backstage/backstage/pull/24681).
+
+### Scaffolder `ui:widget: password` notice
+
+Using `ui:widget: password` does not treat the input as a secret in the Scaffolder, and can lead to exposing some secrets in plaintext, this implementation has been overridden to provide warnings to users that mistakenly use this component and will now render a warning message along with rendering the input in plaintext for additional indication.
+
+Please use the `ui:field: Secret` option instead, as is mentioned in the [using secrets](https://backstage.io/docs/features/software-templates/writing-templates/#using-secrets) documentation.
+
+### New Scaffolder Permissions
+
+The Scaffolder plugin has been upgraded to include additional permissions:
+
+- `scaffolder.task.create`
+- `scaffolder.task.cancel`
+- `scaffolder.task.read`
+
+The new permissions allow you to control who should have read or write access to tasks.
+
+Contributed by [@Zaperex](https://github.com/Zaperex) in [#24518](https://github.com/backstage/backstage/pull/24518).
+
+### Route bindings via app-config
+
+It is now possible to configure route bindings through static configuration, using the `app.routes.bindings` key. For example:
+
+```yaml
+app:
+  routes:
+    bindings:
+      catalog.createComponent: catalog-import.importPage
+```
+
+Is the equivalent of the following:
+
+```ts
+const app = createApp({
+  // ...
+  bindRoutes({ bind }) {
+    bind(catalogPlugin.externalRoutes, {
+      createComponent: catalogImportPlugin.routes.importPage,
+    });
+  },
+});
+```
+
+Additionally, the following default targets have been added for external routes.
+
+- For catalog:
+  - `createComponent` binds to the Scaffolder page.
+  - `viewTechDoc` binds to the TechDocs entity documentation page.
+  - `createFromTemplate` binds to the Scaffolder selected template page
+- For scaffolder:
+  - `registerComponent` binds to the catalog import page.
+  - `viewTechDoc` binds to the TechDocs entity documentation page.
+
+## Security Fixes
+
+This release does not contain any security fixes.
+
+## 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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
+
+### Test utilities
+
+There is now a `TestCaches` class in `@backstage/backend-test-utils` that functions just like `TestDatabases`. This may help in testing out cache based flows against actual cache implementations, using `testcontainers` if available!
+
+### Notifications improvements
+
+The notifications system has received numerous updates, including the ability to perform in-flight processing of notifications. The related signals subsystem now also powers real time updates of the user settings plugin. Thanks to the notifications maintainers for their tireless efforts in this exciting area!
+
+## Links and References
+
+Below you can find a list of links and references to help you learn about and start using this new release.
+
+- [Backstage official website](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
+- [GitHub repository](https://github.com/backstage/backstage)
+- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
+- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
+- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.28.0-changelog.md)
+- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
+
+Sign up for our [newsletter](https://info.backstage.spotify.com/newsletter_subscribe) if you want to be informed about what is happening in the world of Backstage.
+
+Big shoutout to all 64 of you amazing folks who chipped in on this release 🙏: [@acierto](https://github.com/acierto), [@adityak60](https://github.com/adityak60), [@adsk-mukul](https://github.com/adsk-mukul), [@alexef](https://github.com/alexef), [@andrei-ivanovici](https://github.com/andrei-ivanovici), [@anicke](https://github.com/anicke), [@aramissennyeydd](https://github.com/aramissennyeydd), [@awanlin](https://github.com/awanlin), [@benjdlambert](https://github.com/benjdlambert), [@benjidotsh](https://github.com/benjidotsh), [@bethgriggs](https://github.com/bethgriggs), [@brianphillips](https://github.com/brianphillips), [@brunobastosg](https://github.com/brunobastosg), [@camilaibs](https://github.com/camilaibs), [@cjlee01](https://github.com/cjlee01), [@cmoulliard](https://github.com/cmoulliard), [@davidfestal](https://github.com/davidfestal), [@debsmita1](https://github.com/debsmita1), [@drodil](https://github.com/drodil), [@dweber019](https://github.com/dweber019), [@elaine-mattos](https://github.com/elaine-mattos), [@erik-adsk](https://github.com/erik-adsk), [@fabian-m-95](https://github.com/fabian-m-95), [@freben](https://github.com/freben), [@grantila](https://github.com/grantila), [@huggingpixels](https://github.com/huggingpixels), [@ismailmmd](https://github.com/ismailmmd), [@jeevaramanathan](https://github.com/jeevaramanathan), [@johanhammar](https://github.com/johanhammar), [@jslott2sigma](https://github.com/jslott2sigma), [@julien-hery](https://github.com/julien-hery), [@kalleericson](https://github.com/kalleericson), [@kissmikijr](https://github.com/kissmikijr), [@kuangp](https://github.com/kuangp), [@maetis](https://github.com/maetis), [@marcpalm](https://github.com/marcpalm), [@marcuseide](https://github.com/marcuseide), [@mareklibra](https://github.com/mareklibra), [@mario-mui](https://github.com/mario-mui), [@matteosilv](https://github.com/matteosilv), [@mclarke47](https://github.com/mclarke47), [@npiyush97](https://github.com/npiyush97), [@nurbaysymbat](https://github.com/nurbaysymbat), [@parsifal-m](https://github.com/parsifal-m), [@piatkiewicz](https://github.com/piatkiewicz), [@raffitamizian](https://github.com/raffitamizian), [@rbillon59](https://github.com/rbillon59), [@rewixe](https://github.com/rewixe), [@rugvip](https://github.com/rugvip), [@ryan-hanchett](https://github.com/ryan-hanchett), [@sblausten](https://github.com/sblausten), [@snowblitzer](https://github.com/snowblitzer), [@stanislav-c](https://github.com/stanislav-c), [@stephenglass](https://github.com/stephenglass), [@stijnbrouwers](https://github.com/stijnbrouwers), [@suniljose25](https://github.com/suniljose25), [@tcardonne](https://github.com/tcardonne), [@vadave](https://github.com/vadave), [@veenarm](https://github.com/veenarm), [@vinisdl](https://github.com/vinisdl), [@vinzscam](https://github.com/vinzscam), [@waldirmontoya25](https://github.com/waldirmontoya25), [@ydayagi](https://github.com/ydayagi), [@zaperex](https://github.com/zaperex).

microsite/docusaurus.config.ts

@@ -241,7 +241,7 @@ const config: Config = {
           position: 'left',
         },
         {
-          to: 'docs/releases/v1.27.0',
+          to: 'docs/releases/v1.28.0',
           label: 'Releases',
           position: 'left',
         },

microsite/sidebars.json

@@ -1,6 +1,7 @@
 {
   "releases": {
     "Release Notes": [
+      "releases/v1.28.0",
       "releases/v1.27.0",
       "releases/v1.26.0",
       "releases/v1.25.0",