Updated the READMEs

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
2023-12-01 13:55:31 -06:00
parent 2dc72e1817
commit d7d730c4d8
2 changed files with 87 additions and 6 deletions
@@ -8,7 +8,7 @@ The following sections will help you get the Azure DevOps Backend plugin setup a

 ### Configuration

-The Azure DevOps plugin requires the following YAML to be added to your app-config.yaml:
+The Azure DevOps plugin requires the following YAML to be added to your `app-config.yaml`:

 ```yaml
 azureDevOps:
@@ -23,6 +23,12 @@ Configuration Details:
 - `AZURE_TOKEN` environment variable must be set to a [Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) with read access to both Code and Build
 - `organization` is your Azure DevOps Services (cloud) Organization name or for Azure DevOps Server (on-premise) this will be your Collection name

+#### Multi Organization
+
+To support cases where you have multiple Azure DevOps organizations you will want to make sure to configure them in the `integrations.azure` section of your `app-config.yaml` as detailed in the [Azure DevOps Locations](https://backstage.io/docs/integrations/azure/locations) documentation.
+
+**Note:** You will still need to define the [configuration above](#configuration).
+
 ### Up and Running

 Here's how to get the backend up and running:
@@ -112,6 +118,39 @@ The Azure DevOps backend plugin includes the `AzureDevOpsAnnotatorProcessor` whi
  }
 ```

+To use this with the New Backend System you'll want to create a [backend module extension for the Catalog](https://backstage.io/docs/backend-system/building-backends/migrating#other-catalog-extensions) if you haven't already. Here's a basic example of this assuming you are only adding the `AzureDevOpsAnnotatorProcessor`, this would go in your `packages/backend/index.ts`:
+
+```diff
+   import { createBackend } from '@backstage/backend-defaults';
+  import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
+  import { coreServices, createBackendModule } from '@backstage/backend-plugin-api';
+  import { AzureDevOpsAnnotatorProcessor } from '@backstage/plugin-azure-devops-backend';
+
+  const catalogModuleCustomExtensions = createBackendModule({
+    pluginId: 'catalog', // name of the plugin that the module is targeting
+    moduleId: 'custom-extensions',
+    register(env) {
+      env.registerInit({
+        deps: {
+          catalog: catalogProcessingExtensionPoint,
+          config: coreServices.rootConfig,
+        },
+        async init({ catalog, config }) {
+          catalog.addProcessor(AzureDevOpsAnnotatorProcessor.fromConfig(config));
+        },
+      });
+    },
+  });
+
+   const backend = createBackend();
+
+   // ... other feature additions
+
+  backend.add(catalogModuleCustomExtensions());
+
+   backend.start();
+```
+
 ## Links

 - [Frontend part of the plugin](https://github.com/backstage/backstage/tree/master/plugins/azure-devops)
@@ -72,6 +72,53 @@ dev.azure.com/build-definition: <build-definition-name>

 In this case `<project-name>` will be the name of your Team Project and `<build-definition-name>` will be the name of the Build Definition you would like to see Builds for, and it's possible to add more Builds separated by a comma. If the Build Definition name has spaces in it make sure to put quotes around it.

+#### Multiple Organizations
+
+If you you have multiple organizations you'll need to also add this annotation:
+
+```yaml
+dev.azure.com/host-org: <host>/<organization>
+```
+
+For this annotation `<host>` will match the `host` value in the `integrations.azure` section in your `app-config.yaml` and `<organization>` will be the name of the Organization that is part of the `host`. Let's break this down with an example:
+
+Say we have the following `integrations.azure` section:
+
+```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}
+    - host: server.company.com
+      credentials:
+        - organizations:
+            - yet-another-org
+          personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
+```
+
+If the entity we are viewing lives in the `my-other-org` organization then the `dev.azure.com/host-org` annotation would look like this:
+
+```yaml
+dev.azure.com/host-org: dev.azure.com/my-other-org
+```
+
+And if the entity was from `yet-another-org` it would look like this:
+
+```yaml
+dev.azure.com/host-org: server.company.com/yet-another-org
+```
+
+**Note:** To save you time, effort, and confusion setting up these annotations manually you can use the `AzureDevOpsAnnotatorProcessor` processor which will add the `dev.azure.com/host-org` and `dev.azure.com/project-repo` annotations for you with the correct values. The Azure DevOps backend plugin has details on how to [add this processor](https://github.com/backstage/backstage/tree/master/plugins/azure-devops-backend#processor).
+
 ### Azure Pipelines Component

 To get the Azure Pipelines component working you'll need to do the following two steps:
@@ -247,8 +294,3 @@ To get the README component working you'll need to do the following two steps:
 - You'll need to add the `EntitySwitch.Case` above from step 2 to all the entity sections you want to see Readme in. For example if you wanted to see Readme when looking at Website entities then you would need to add this to the `websiteEntityPage` section.
 - The `if` prop is optional on the `EntitySwitch.Case`, you can remove it if you always want to see the tab even if the entity being viewed does not have the needed annotation
 - The `maxHeight` property on the `EntityAzureReadmeCard` will set the maximum screen size you would like to see, if not set it will default to 100%
-
-## Limitations
-
- Currently multiple organizations are not supported
- Mixing Azure DevOps Services (cloud) and Azure DevOps Server (on-premise) is not supported