Merge pull request #22791 from DavidRobertsOrbis/azd-readme-location

azure-devops plugin: Ability to fetch the README file from a different AZD path

plugins/azure-devops/README.md

@@ -63,13 +63,19 @@ spec:
 
 #### Mono repos
 
-If you have multiple entities within a single repo, you will need to specify which pipelines belong to each entity.
+If you have multiple entities within a single repo, you will need to specify which pipelines belong to each entity, like this:
 
 ```yaml
 dev.azure.com/project-repo: <my-project>/<my-repo>
 dev.azure.com/build-definition: <build-definition-name>
 ```
 
+Then to display the `README` file that belongs to each entity you would do this:
+
+```yaml
+dev.azure.com/readme-path: /<path-to>/<my-readme-file>.md
+```
+
 #### Pipeline in different project to repo
 
 If your pipeline is in a different project to the source code, you will need to specify this in the project annotation.

plugins/azure-devops/src/api/AzureDevOpsClient.ts

@@ -189,6 +189,9 @@ export class AzureDevOpsClient implements AzureDevOpsApi {
     if (opts.org) {
       queryString.append('org', opts.org);
     }
+    if (opts.path) {
+      queryString.append('path', opts.path);
+    }
     return await this.get(
       `readme/${encodeURIComponent(opts.project)}/${encodeURIComponent(
         opts.repo,

plugins/azure-devops/src/hooks/useReadme.ts

@@ -30,8 +30,15 @@ export function useReadme(entity: Entity): {
   const api = useApi(azureDevOpsApiRef);
 
   const { value, loading, error } = useAsync(() => {
-    const { project, repo, host, org } = getAnnotationValuesFromEntity(entity);
-    return api.getReadme({ project, repo: repo as string, host, org });
+    const { project, repo, host, org, readmePath } =
+      getAnnotationValuesFromEntity(entity);
+    return api.getReadme({
+      project,
+      repo: repo as string,
+      host,
+      org,
+      path: readmePath,
+    });
   }, [api]);
 
   return {

plugins/azure-devops/src/utils/getAnnotationValuesFromEntity.test.ts

@@ -52,6 +52,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: 'repoName',
         definition: undefined,
+        readmePath: undefined,
         host: undefined,
         org: undefined,
       });
@@ -149,6 +150,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: undefined,
         definition: 'buildDefinitionName',
+        readmePath: undefined,
         host: undefined,
         org: undefined,
       });
@@ -220,6 +222,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: 'repoName',
         definition: undefined,
+        readmePath: undefined,
         host: 'hostName',
         org: 'organizationName',
       });
@@ -246,6 +249,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: undefined,
         definition: 'buildDefinitionName',
+        readmePath: undefined,
         host: 'hostName',
         org: 'organizationName',
       });
@@ -344,6 +348,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: 'repoName',
         definition: undefined,
+        readmePath: undefined,
         host: 'company.com/tfs',
         org: 'organizationName',
       });
@@ -417,6 +422,7 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: 'repoName',
         definition: 'buildDefinitionName',
+        readmePath: undefined,
         host: undefined,
         org: undefined,
       });
@@ -443,6 +449,87 @@ describe('getAnnotationValuesFromEntity', () => {
         project: 'projectName',
         repo: undefined,
         definition: 'buildDefinitionName',
+        readmePath: undefined,
+        host: undefined,
+        org: undefined,
+      });
+    });
+  });
+
+  describe('definition, project and readme', () => {
+    it('returns with the readme path', () => {
+      const entity: Entity = {
+        apiVersion: 'backstage.io/v1alpha1',
+        kind: 'Component',
+        metadata: {
+          namespace: 'default',
+          name: 'project-repo',
+          annotations: {
+            'dev.azure.com/project': 'projectName',
+            'dev.azure.com/build-definition': 'buildDefinitionName',
+            'dev.azure.com/readme-path': 'readme/path.md',
+          },
+        },
+      };
+      const values = getAnnotationValuesFromEntity(entity);
+      expect(values).toEqual({
+        project: 'projectName',
+        repo: undefined,
+        definition: 'buildDefinitionName',
+        readmePath: 'readme/path.md',
+        host: undefined,
+        org: undefined,
+      });
+    });
+  });
+
+  describe('definition, projectRepo and readme', () => {
+    it('returns with the readme path', () => {
+      const entity: Entity = {
+        apiVersion: 'backstage.io/v1alpha1',
+        kind: 'Component',
+        metadata: {
+          namespace: 'default',
+          name: 'project-repo',
+          annotations: {
+            'dev.azure.com/project-repo': 'projectName/repoName',
+            'dev.azure.com/build-definition': 'buildDefinitionName',
+            'dev.azure.com/readme-path': 'readme/path.md',
+          },
+        },
+      };
+      const values = getAnnotationValuesFromEntity(entity);
+      expect(values).toEqual({
+        project: 'projectName',
+        repo: 'repoName',
+        definition: 'buildDefinitionName',
+        readmePath: 'readme/path.md',
+        host: undefined,
+        org: undefined,
+      });
+    });
+  });
+
+  describe('projectRepo and readme', () => {
+    it('returns with the readme path', () => {
+      const entity: Entity = {
+        apiVersion: 'backstage.io/v1alpha1',
+        kind: 'Component',
+        metadata: {
+          namespace: 'default',
+          name: 'project-repo',
+          annotations: {
+            'dev.azure.com/project-repo': 'projectName/repoName',
+            'dev.azure.com/readme-path': 'readme/path.md',
+          },
+        },
+      };
+      const values = getAnnotationValuesFromEntity(entity);
+      expect(values).toEqual({
+        project: 'projectName',
+        repo: 'repoName',
+        definition: undefined,
+        readmePath: 'readme/path.md',
         host: undefined,
         org: undefined,
       });

plugins/azure-devops/src/utils/getAnnotationValuesFromEntity.ts

@@ -18,6 +18,7 @@ import { Entity } from '@backstage/catalog-model';
 import {
   AZURE_DEVOPS_PROJECT_ANNOTATION,
   AZURE_DEVOPS_BUILD_DEFINITION_ANNOTATION,
+  AZURE_DEVOPS_README_ANNOTATION,
   AZURE_DEVOPS_REPO_ANNOTATION,
   AZURE_DEVOPS_HOST_ORG_ANNOTATION,
 } from '@backstage/plugin-azure-devops-common';
@@ -28,6 +29,7 @@ export function getAnnotationValuesFromEntity(entity: Entity): {
   definition?: string;
   host?: string;
   org?: string;
+  readmePath?: string;
 } {
   const hostOrg = getHostOrg(entity.metadata.annotations);
   const projectRepo = getProjectRepo(entity.metadata.annotations);
@@ -35,12 +37,15 @@ export function getAnnotationValuesFromEntity(entity: Entity): {
     entity.metadata.annotations?.[AZURE_DEVOPS_PROJECT_ANNOTATION];
   const definition =
     entity.metadata.annotations?.[AZURE_DEVOPS_BUILD_DEFINITION_ANNOTATION];
+  const readmePath =
+    entity.metadata.annotations?.[AZURE_DEVOPS_README_ANNOTATION];
 
   if (definition) {
     if (project) {
       return {
         project,
         definition,
+        readmePath: readmePath,
         ...hostOrg,
       };
     }
@@ -49,6 +54,7 @@ export function getAnnotationValuesFromEntity(entity: Entity): {
         project: projectRepo.project,
         repo: projectRepo.repo,
         definition,
+        readmePath: readmePath,
         ...hostOrg,
       };
     }
@@ -60,6 +66,7 @@ export function getAnnotationValuesFromEntity(entity: Entity): {
       return {
         project: projectRepo.project,
         repo: projectRepo.repo,
+        readmePath: readmePath,
         ...hostOrg,
       };
     }