Merge branch 'master' of github.com:backstage/backstage into GD-294-users-groups-ingestion

2023-08-22 08:33:45 +01:00
parent 880c08c0b0 5a510c9df8
commit 68032afa9a
293 changed files with 5784 additions and 1951 deletions
@@ -85,6 +85,8 @@ declare a dependency on the plugin package itself. This is to avoid a direct
 dependency and potentially cause duplicate installations of the plugin package,
 while duplicate installations of library packages should always be supported.

+To create a Backend module, run `yarn new`, select `backend-module`, and fill out the rest of the prompts. This will create a new package at `plugins/<pluginId>-backend-module-<moduleId>`.
+
 The following is an example of how to create a module that adds a new processor
 using the `catalogProcessingExtensionPoint`:

@@ -23,9 +23,9 @@ compound reference structure.

 ## String References

-This is the most common alternative, that is used in almost all circumstances.
+This is the most common alternative and is used in almost all circumstances.

-The string is on the form `[<kind>:][<namespace>/]<name>`, that is, it is
+The string is of the form `[<kind>:][<namespace>/]<name>`. That is, it is
 composed of between one and three parts in this specific order, without any
 additional encoding:

@@ -19,10 +19,10 @@ Using a service principal:
 integrations:
  azure:
    - host: dev.azure.com
-      credential:
-        clientId: ${CLIENT_ID}
-        clientSecret: ${CLIENT_SECRET}
-        tenantId: ${TENANT_ID}
+      credentials:
+        - clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
 ```

 Using a managed identity:
@@ -31,8 +31,8 @@ Using a managed identity:
 integrations:
  azure:
    - host: dev.azure.com
-      credential:
-        clientId: ${CLIENT_ID}
+      credentials:
+        - clientId: ${AZURE_CLIENT_ID}
 ```

 Using a personal access token (PAT):
@@ -41,24 +41,54 @@ Using a personal access token (PAT):
 integrations:
  azure:
    - host: dev.azure.com
-      token: ${AZURE_TOKEN}
+      credentials:
+        - personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
 ```

+You can use specific credentials for different Azure DevOps organizations by specifying the `organizations` field on the credential:
+
+```yaml
+integrations:
+  azure:
+    - host: dev.azure.com
+      credentials:
+        - organizations:
+            - my-org
+            - my-other-org
+          clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
+        - organizations:
+            - another-org
+          clientId: ${AZURE_CLIENT_ID}
+        - organizations:
+            - yet-another-org
+          personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
+```
+
+If you do not specify the `organizations` field the credential will be used for all organizations for which no other credential is configured.
+
 > Note: An Azure DevOps provider is added automatically at startup for
 > convenience, so you only need to list it if you want to supply a
-> [token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
+> [personalAccessToken](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
 > a [service principal](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity),
 > or a [managed identity](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)

 The configuration is a structure with these elements:

- `host`: The DevOps host; only `dev.azure.com` is supported.
- `token` (optional): A personal access token as expected by Azure DevOps.
- `credential`: (optional): A service principal or managed identity
+- `credentials`: (optional): A service principal, managed identity, or personal access token
+
+The `credentials` element is a structure with these elements:
+
+- `organizations`: (optional): A list of organizations for which this credential should be used. If not specified the credential will be used for all organizations for which no other credential is configured.
+- `clientId`: The client ID of the service principal or managed identity (required for service principal and managed identities)
+- `clientSecret`: The client secret of the service principal (required for service principal)
+- `tenantId`: The tenant ID of the service principal (required for service principal)
+- `personalAccessToken`: The personal access token (required for personal access token)

 > Note:
 >
-> - `token` and `credential` are mutually exclusive.
 > - You cannot use a service principal or managed identity for Azure DevOps Server (on-premises) organizations
 > - You can only use a service principal or managed identity for Azure AD backed Azure DevOps organizations
-> - The token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
+> - You can only specify one credential per host without any organizations specified
+> - The personal access token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
@@ -18,6 +18,22 @@ PR is merged. This is typically done every Tuesday around noon CET.
 **This emergency release process is intended only for the Backstage
 maintainers.**

+Given one or more PRs towards master that we want to create a patch release for, run the following script from the repo root:
+
+```bash
+./scripts/patch-release-for-pr.js <pr-number> <pr-number-2> ...
+```
+
+Wait until the script has finished executing, at the end of the output you will find a link of the format `https://github.com/backstage/backstage/compare/patch/...`. Open this link in your browser to create a PR for the patch release. Finish the sentence "This release fixes an issue where..." and create the PR.
+
+Once the PR has been approved and merged, the patch release will be automatically created. The patch release is complete when a notification has been posted to Discord in the `#announcements` channel. Keep an eye on "Deploy Packages" workflow and re-trigger if it fails. It is safe to re-trigger any part of this workflow, including the release step.
+
+If the above process fails, you can fall back to the manual process documented below.
+
+### Old Process
+
+This is the old and manual process that we used before the patch script, provided here as a reference:
+
 For this example we will be using the `@backstage/plugin-foo` package as an
 example and assume that it is currently version `6.5.0` in the master branch.