Merge pull request #23462 from awanlin/topic/azure-devops-optional-config

Azure DevOps config is now optional

.changeset/spicy-eels-cheat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-azure-devops-backend': patch
+---
+
+The `azureDevOps` configuration section is now optional and the `azureDevOps.token` has been deprecated. Use `integrations.azure` instead, see the [Azure DevOps Locations](https://backstage.io/docs/integrations/azure/locations) documentation for more details.

plugins/azure-devops-backend/README.md

@@ -6,28 +6,26 @@ Simple plugin that proxies requests to the [Azure DevOps](https://docs.microsoft
 
 The following sections will help you get the Azure DevOps Backend plugin setup and running.
 
-### Configuration
+### Credentials
 
-The Azure DevOps plugin requires the following YAML to be added to your `app-config.yaml`:
+In order to support **Multiple Organizations** as well as **Service Principals** and **Managed Identity** the Azure DevOps plugin relies on the `integrations.azure` section of your `app-config.yaml` being properly configured to be able to access the needed credentials. More details on this can be found in the [Azure DevOps Locations](https://backstage.io/docs/integrations/azure/locations) documentation.
+
+### Single Organization Configuration
+
+For those with a single organization the Azure DevOps plugin requires the following YAML configuration to be added to your `app-config.yaml`:
 
 ```yaml
 azureDevOps:
   host: dev.azure.com
-  token: ${AZURE_TOKEN}
   organization: my-company
 ```
 
 Configuration Details:
 
-- `host` and `token` can be the same as the ones used for the `integration` section
-- `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
+- `host` can be the same as the ones used for the `integration` section
 - `organization` is your Azure DevOps Services (cloud) Organization name or for Azure DevOps Server (on-premise) this will be your Collection name
 
-#### Multi Organization & Service Principals
-
-To support cases where you have multiple Azure DevOps organizations and/or you want to use a Service Principal 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).
+> Note: The credentials in this setup would still need to be defined in your `integrations.azure` section of your `app-config.yaml` as noted in the [Credentials](#credentials) section above.
 
 ### Up and Running
 

plugins/azure-devops-backend/config.d.ts

@@ -18,7 +18,7 @@ export interface Config {
   /**
    * Configuration options for the azure-devops-backend plugin
    */
-  azureDevOps: {
+  azureDevOps?: {
     /**
      * The hostname of the given Azure instance
      */
@@ -26,6 +26,7 @@ export interface Config {
     /**
      * Token used to authenticate requests.
      * @visibility secret
+     * @deprecated Use `integrations.azure` instead, see {@link https://backstage.io/docs/integrations/azure/locations}
      */
     token: string;
     /**

plugins/azure-devops-backend/src/api/AzureDevOpsApi.ts

@@ -108,10 +108,17 @@ export class AzureDevOpsApi {
     // If no host or org is provided we fall back to the values from the `azureDevOps` config section
     // these may have been setup in the `integrations.azure` config section
     // which is why use them here and not just falling back on them entirely
-    const validHost = host ?? this.config.getString('azureDevOps.host');
-    const validOrg = org ?? this.config.getString('azureDevOps.organization');
-    const url = `https://${validHost}/${encodeURIComponent(validOrg)}`;
+    const validHost = host ?? this.config.getOptionalString('azureDevOps.host');
+    const validOrg =
+      org ?? this.config.getOptionalString('azureDevOps.organization');
 
+    if (!validHost || !validOrg) {
+      throw new Error(
+        "No 'host' or 'org' provided in annotations or configuration, unable to retrieve needed credentials",
+      );
+    }
+
+    const url = `https://${validHost}/${encodeURIComponent(validOrg)}`;
     const credentials = await this.credentialsProvider.getCredentials({
       url,
     });
@@ -120,7 +127,15 @@ export class AzureDevOpsApi {
     if (!credentials) {
       // No credentials found for the provided host and org in the `integrations.azure` config section
       // use the fall back personal access token from `azureDevOps.token`
-      const token = this.config.getString('azureDevOps.token');
+      const token = this.config.getOptionalString('azureDevOps.token');
+      if (!token) {
+        throw new Error(
+          "No 'azureDevOps.token' provided in configuration and credentials were not found in 'integrations.azure', unable to proceed",
+        );
+      }
+      this.logger.warn(
+        "Using the token from 'azureDevOps.token' has been deprecated, use 'integrations.azure' instead, for more details see: https://backstage.io/docs/integrations/azure/locations",
+      );
       authHandler = getPersonalAccessTokenHandler(token);
     } else {
       authHandler = getHandlerFromToken(credentials.token);

plugins/azure-devops-backend/src/service/router.ts

@@ -59,6 +59,12 @@ export async function createRouter(
 ): Promise<express.Router> {
   const { logger, reader, config, permissions } = options;
 
+  if (config.getString('azureDevOps.token')) {
+    logger.warn(
+      "The 'azureDevOps.token' has been deprecated, use 'integrations.azure' instead, for more details see: https://backstage.io/docs/integrations/azure/locations",
+    );
+  }
+
   const permissionIntegrationRouter = createPermissionIntegrationRouter({
     permissions: azureDevOpsPermissions,
   });