Merge branch 'master' into Update_doc_auth_github

Signed-off-by: Aditya Kumar <136452216+AdityaK60@users.noreply.github.com>

docs/auth/atlassian/provider.md

@@ -71,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/github/provider.md

@@ -43,13 +43,12 @@ auth:
         # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
         signIn:
           resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # Matches the GitHub username with the Backstage user entity name.
+            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
             - resolver: usernameMatchingUserEntityName
 ```
 
-The GitHub provider is a structure with three configuration keys:
+The GitHub provider is a structure with these configuration keys:
 
 - `clientId`: The client ID that you generated on GitHub, e.g.
   `b59241722e3c3b4816e2`
@@ -60,6 +59,9 @@ The GitHub provider is a structure with three configuration keys:
   initiating an OAuth flow, e.g.
   `https://your-intermediate-service.com/handler`. Only needed if Backstage is
   not the immediate receiver (e.g. one OAuth app for many backstage instances).
+- `signIn`: The configuration for the sign-in process, including the **resolvers**
+  that should be used to match the user from the auth provider with the user
+  entity in the Backstage catalog (typically a single resolver is sufficient).
 
 ### Resolvers
 

docs/auth/gitlab/provider.md

@@ -70,7 +70,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/google/gcp-iap-auth.md

@@ -50,7 +50,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/google/provider.md

@@ -64,7 +64,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `google.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/microsoft/provider.md

@@ -84,7 +84,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `microsoft.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/oauth2-proxy/provider.md

@@ -40,7 +40,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `forwardedUserMatchingUserEntityName`: Matches the value in the `x-forwarded-user` header from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/okta/provider.md

@@ -75,7 +75,11 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `emailMatchingUserEntityAnnotation`: Matches the email address from the auth provider with the User entity where the value of the `okta.com/email` annotation matches. If no match is found it will throw a `NotFoundError`.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.
 

docs/auth/vmware-cloud/provider.md

@@ -176,6 +176,10 @@ This provider includes several resolvers out of the box that you can use:
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
 - `vmwareCloudSignInResolvers`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will sign in the user without associating with a catalog user.
 
-> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.

docs/backend-system/building-backends/01-index.md

@@ -6,8 +6,12 @@ sidebar_label: Overview
 description: Building backends using the new backend system
 ---
 
-> NOTE: If you have an existing backend that is not yet using the new backend
-> system, see [migrating](./08-migrating.md).
+:::note Note
+
+If you have an existing backend that is not yet using the new backend
+system, see [migrating](./08-migrating.md).
+
+:::
 
 This section covers how to set up and customize your own Backstage backend. It covers some aspects of how backend instances fit into the larger system, but for a more in-depth explanation of the role of backends in the backend system, see [the architecture section](../architecture/02-backends.md).
 

docs/backend-system/building-backends/08-migrating.md

@@ -201,10 +201,14 @@ const legacyPlugin = makeLegacyPlugin(
 After this, your backend will know how to instantiate your thing on demand and
 place it in the legacy plugin environment.
 
-> NOTE: If you happen to be dealing with a service ref that does NOT have a
-> default implementation, but rather has a separate service factory, then you
-> will also need to import that factory and pass it to the `services` array
-> argument of `createBackend`.
+:::note Note
+
+If you happen to be dealing with a service ref that does NOT have a
+default implementation, but rather has a separate service factory, then you
+will also need to import that factory and pass it to the `services` array
+argument of `createBackend`.
+
+:::
 
 ## Cleaning Up the Plugins Folder
 
@@ -216,10 +220,14 @@ maintained by the Backstage maintainers, you may find that they have already
 been migrated to the new backend system. This section describes some specific
 such migrations you can make.
 
-> NOTE: For each of these, note that your backend still needs to have a
-> dependency (e.g. in `packages/backend/package.json`) to those plugin packages,
-> and they still need to be configured properly in your app-config. Those
-> mechanisms still work just the same as they used to in the old backend system.
+:::note Note
+
+For each of these, note that your backend still needs to have a
+dependency (e.g. in `packages/backend/package.json`) to those plugin packages,
+and they still need to be configured properly in your app-config. Those
+mechanisms still work just the same as they used to in the old backend system.
+
+:::
 
 ### The App Plugin
 
@@ -880,7 +888,11 @@ auth:
             - resolver: emailMatchingUserEntityAnnotation
 ```
 
-> Note: the resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+:::note Note
+
+The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
+
+:::
 
 #### Auth Plugin Modules and Their Resolvers
 
@@ -1137,7 +1149,11 @@ backend.add(import('@backstage/plugin-search-backend/alpha'));
 /* highlight-add-end */
 ```
 
-> Note: this will use the Lunr search engine which stores its index in memory
+:::note Note
+
+This will use the Lunr search engine which stores its index in memory.
+
+:::
 
 #### Search Engines
 
@@ -1226,7 +1242,11 @@ backend.add(
 /* highlight-add-end */
 ```
 
-> Note: The above example includes a default allow-all policy. If that is not what you want, do not add the second line and instead investigate one of the options below.
+:::note Note
+
+The above example includes a default allow-all policy. If that is not what you want, do not add the second line and instead investigate one of the options below.
+
+:::
 
 #### Custom Permission Policy
 

docs/features/software-catalog/system-model.md

@@ -120,6 +120,9 @@ product or use-case, share the same entity types in their APIs, and integrate
 well with each other. Other domains could be “Content Ingestion”, “Ads” or
 “Search”.
 
+In case of a large organization, it might make sense to further group domains
+in a hierarchy, where a domain can be a subdomain of another domain.
+
 ## Other
 
 ### Location

docs/integrations/github/org.md

@@ -90,7 +90,7 @@ Directly under the `githubOrg` is a list of configurations, each entry is a stru
 
 - `id`: A stable id for this provider. Entities from this provider will be associated with this ID, so you should take care not to change it over time since that may lead to orphaned entities and/or conflicts.
 - `githubUrl`: The target that this provider should consume
-- `orgs` (optional): The list of the GitHub orgs to consume. By default wil consume all accessible orgs on the given GitHub instance (support for GitHub App integration only).
+- `orgs` (optional): The list of the GitHub orgs to consume. If you only list a single org the generated group entities will use the `default` namespace, otherwise they will use the org name as the namespace. By default the provider will consume all accessible orgs on the given GitHub instance (support for GitHub App integration only).
 - `schedule`: The refresh schedule to use, matches the structure of [`TaskScheduleDefinitionConfig`](https://backstage.io/docs/reference/backend-tasks.taskscheduledefinitionconfig/)
 
 ### Events Support

docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md

@@ -144,7 +144,11 @@ export const rules = { isOwner };
 
 `makeCreatePermissionRule` is a helper used to ensure that rules created for this plugin use consistent types for the resource and query.
 
-> Note: To support custom rules defined by Backstage integrators, you must export `createTodoListPermissionRule` from the backend package and provide some way for custom rules to be passed in before the backend starts, likely via `createRouter`.
+:::note Note
+
+To support custom rules defined by Backstage integrators, you must export `createTodoListPermissionRule` from the backend package and provide some way for custom rules to be passed in before the backend starts, likely via `createRouter`.
+
+:::
 
 We have created a new `isOwner` rule, which is going to be automatically used by the permission framework whenever a conditional response is returned in response to an authorized request with an attached `resourceRef`.
 Specifically, the `apply` function is used to understand whether the passed resource should be authorized or not.

docs/releases/v1.27.0.md

@@ -0,0 +1,83 @@
+---
+id: v1.27.0
+title: v1.27.0
+description: Backstage Release v1.27.0
+---
+
+These are the release notes for the v1.27.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
+
+### Backend System Deprecations
+
+As part of the [work towards a stable 1.0 release of the new backend system](https://github.com/backstage/backstage/issues/24493), we will deprecate and move or remove several utilities from `@backstage/backend-common`. This release contains a few of these deprecations, with more to be expected in the future. The long-term goal is to completely deprecate and remove the `@backstage/backend-common` package.
+
+### Hierarchical Domains
+
+The Backstage System Model has been tweaked with the addition of a hierarchy of `Domain` entities. The change includes a new `spec.subdomainOf` property on the `Domain` entity, which can be used to express that a domain has a `partOf` (and conversely, `hasPart`) relation toward another domain.
+
+Contributed by [@dawngerpony](https://github.com/dawngerpony) and [@janogonzalez](https://github.com/janogonzalez) in [#17125](https://github.com/backstage/backstage/pull/17125).
+
+### Scaffolder workspace serialization
+
+Added experimental support for serialization of workspaces in the scaffolder. By serializing the workspace, it is possible to re-run the task in a non-sticky way. This means that the task can be restored and retried on a different scaffolder task worker.
+
+To enable this feature, set the `EXPERIMENTAL_workspaceSerialization` option to `true` in the `scaffolder` section of the `app-config.yaml` file:
+
+```yaml
+scaffolder:
+  EXPERIMENTAL_workspaceSerialization: true
+```
+
+Contributed by [@acierto](https://github.com/acierto) in [#24570](https://github.com/backstage/backstage/pull/24570).
+
+### Scaffolder `notification:send` action
+
+The new `notification:send` action allows sending notifications from templates. This can be used to send notifications to users when executing a template. Please note that the notifications system is still under development.
+
+To install this action, add the new module to your backend:
+
+```diff
++ backend.add(import('@backstage/plugin-scaffolder-backend-module-notifications'));
+```
+
+Contributed by [@drodil](https://github.com/drodil) in [#24588](https://github.com/backstage/backstage/pull/24588).
+
+### Backend Authentication
+
+The requirement to configure a secret for backend authentication in production has been removed. It is now only needed if you rely on the [legacy authentication mechanism](https://backstage.io/docs/auth/service-to-service-auth#external-callers-legacy). If you don’t configure any secrets you will also not be able to generate tokens with the `TokenManager` service, although use of this service is discouraged as it has been replaced by the `AuthService`.
+
+### User Authentication
+
+The `auth` backend plugin now provides an `authOwnershipResolutionExtensionPoint` that lets you override the default ownership resolution used by sign-in resolvers. This allows you to customize this logic for all sign-in resolvers without replacing them.
+
+Contributed by [@drodil](https://github.com/drodil) in [#22765](https://github.com/backstage/backstage/pull/22765).
+
+### Events support for GitLab Entity and Org Discovery
+
+The `GitlabDiscoveryEntityProvider` and `GitlabOrgDiscoveryEntityProvider` can now be configured to receive events from GitLab. This allows for the automatic discovery of entities in Backstage when groups or users are created or updated in GitLab.
+
+Contributed by [@elaine-mattos](https://github.com/elaine-mattos) in [#23373](https://github.com/backstage/backstage/pull/23373).
+
+## 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).
+
+## 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.27.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.