Backstage Azure Pipelines Plugin

Install the frontend package

1. Add the package to your app

   Copy

   yarn --cwd packages/app add @backstage-community/plugin-azure-devops

Show Azure Pipelines in the entity page

If your entities use dev.azure.com/project-repo

1. Update the entity page

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import { EntitySwitch } from '@backstage/plugin-catalog';
   import {
     EntityAzurePipelinesContent,
     isAzureDevOpsAvailable,
   } from '@backstage-community/plugin-azure-devops';
   
   // For example in your CI CD section
   const cicdContent = (
     <EntitySwitch>
       <EntitySwitch.Case if={isAzureDevOpsAvailable}>
         <EntityAzurePipelinesContent defaultLimit={25} />
       </EntitySwitch.Case>
     </EntitySwitch>
   );

If your entities use dev.azure.com/project and dev.azure.com/build-definitionz

1. Update the entity page

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import { EntitySwitch } from '@backstage/plugin-catalog';
   import {
     EntityAzurePipelinesContent,
     isAzurePipelinesAvailable,
   } from '@backstage-community/plugin-azure-devops';
   
   // For example in your CI CD section
   const cicdContent = (
     <EntitySwitch>
       <EntitySwitch.Case if={isAzurePipelinesAvailable}>
         <EntityAzurePipelinesContent defaultLimit={25} />
       </EntitySwitch.Case>
     </EntitySwitch>
   );

Note
You can remove the if guard if you want the tab to always render
defaultLimit sets the max number of builds to show and defaults to ten

Configure Azure DevOps integration

1. Add Azure DevOps credentials in your app config

   Copy

   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}

Add entity annotations

Use one of these setups

Repo with pipelines in the same project

# catalog-info.yaml
metadata:
  annotations:
    dev.azure.com/project-repo: my-project/my-repo

Monorepo with pipelines per entity

metadata:
  annotations:
    dev.azure.com/project-repo: my-project/my-repo
    dev.azure.com/build-definition: my-build-definition

If you want a readme for each entity in a monorepo

metadata:
  annotations:
    dev.azure.com/readme-path: /services/my-service/README.md

Note
The readme path must be absolute in the repo
Relative paths are not supported by the Azure DevOps API

Pipeline in a different project than the repo

metadata:
  annotations:
    dev.azure.com/project-repo: project-with-source-code/my-repo
    dev.azure.com/build-definition: my-build-definition
    dev.azure.com/project: project-with-build-code

Pipelines only with another SCM

metadata:
  annotations:
    dev.azure.com/project: my-project
    dev.azure.com/build-definition: "My Build With Spaces"

You can list more than one build definition separated by a comma

Multiple organizations

If you have more than one organization set in integrations azure add this

metadata:
  annotations:
    dev.azure.com/host-org: dev.azure.com/my-other-org

If you use a different host value in integrations azure match that host

metadata:
  annotations:
    dev.azure.com/host-org: server.company.com/yet-another-org

Names with spaces

Spaces in project and repo names are supported

metadata:
  annotations:
    dev.azure.com/project-repo: Has Spaces/With Space

Quotes are fine too

metadata:
  annotations:
    dev.azure.com/project: 'Has Spaces'

Install the backend plugin classic backend system

The backend plugin is required. Install it and mount its router.

1. Add the backend package

   Copy

   yarn --cwd packages/backend add @backstage-community/plugin-azure-devops-backend

2. Create the plugin router

   Copy

   // packages/backend/src/plugins/azureDevOps.ts
   import { Router } from 'express';
   import { createRouter } from '@backstage-community/plugin-azure-devops-backend';
   import { PluginEnvironment } from '../types';
   
   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       discovery: env.discovery,
       tokenManager: env.tokenManager,
       permissions: env.permissions,
       identity: env.identity,
     });
   }

3. Mount the router

   Copy

   // packages/backend/src/index.ts
   import azureDevOps from './plugins/azureDevOps';
   
   const azureDevOpsEnv = useHotMemoize(module, () => createEnv('azure-devops'));
   
   async function main() {
     // ...
     const apiRouter = Router();
     // ...
     apiRouter.use(
       '/azure-devops',
       await azureDevOps(azureDevOpsEnv),
     );
     // ...
     await startStandaloneServer({ logger, router: apiRouter });
   }
   
   main().catch(error => {
     logger.error(error);
     process.exit(1);
   });

Note
The backend reads credentials from integrations azure in your config
Use the same config shown earlier

New backend system status

At this time the Azure DevOps backend plugin is provided as a classic router
Use the classic setup above in a new backend instance through the legacy router adapter if your app uses the new backend system

Example using the legacy adapter

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';
import { createRouter } from '@backstage-community/plugin-azure-devops-backend';

const backend = createBackend();

backend.addLegacyRouter(async env => {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    permissions: env.permissions,
    identity: env.identity,
  });
}, '/azure-devops');

backend.start();

If your installation uses a different bootstrap helper adapt the same idea
Mount the legacy router under a path such as /azure-devops

Optional catalog annotator processor

This processor can add dev.azure.com/host-org and dev.azure.com/project-repo for you

1. Add the package

   Copy

   yarn --cwd packages/backend add @backstage-community/plugin-catalog-backend-module-azure-devops-annotator-processor

2. Register the processor

   Copy

   // packages/backend/src/plugins/catalog.ts
   import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
   import { AzureDevOpsAnnotatorProcessor } from '@backstage-community/plugin-catalog-backend-module-azure-devops-annotator-processor';
   
   export default async function createPlugin(env: PluginEnvironment) {
     const builder = await CatalogBuilder.create(env);
     builder.addProcessor(new AzureDevOpsAnnotatorProcessor(env.config));
     const { processingEngine, router } = await builder.build();
     await processingEngine.start();
     return router;
   }

Permission setup

The plugin supports the permission framework for pipelines and other features

1. Add the common package to your backend where your permission policy lives

   Copy

   yarn --cwd packages/backend add @backstage-community/plugin-azure-devops-common

2. Update your permission policy

   Copy

   // packages/backend/src/plugins/permission.ts or your policy file
   import {
     azureDevOpsPullRequestReadPermission,
     azureDevOpsPipelineReadPermission,
     azureDevOpsGitTagReadPermission,
     azureDevOpsReadmeReadPermission,
     azureDevOpsPullRequestDashboardReadPermission,
   } from '@backstage-community/plugin-azure-devops-common';
   import {
     AuthorizeResult,
     PolicyDecision,
     isPermission,
   } from '@backstage/plugin-permission-common';
   import {
     catalogConditions,
     createCatalogConditionalDecision,
   } from '@backstage/plugin-catalog-backend/alpha';
   
   export class MyPermissionPolicy /* implements PermissionPolicy */ {
     async handle(request: PolicyQuery, user?: BackstageIdentityResponse): Promise<PolicyDecision> {
       if (
         isPermission(request.permission, azureDevOpsPullRequestReadPermission) ||
         isPermission(request.permission, azureDevOpsPipelineReadPermission) ||
         isPermission(request.permission, azureDevOpsGitTagReadPermission) ||
         isPermission(request.permission, azureDevOpsReadmeReadPermission)
       ) {
         return createCatalogConditionalDecision(
           request.permission,
           catalogConditions.isEntityOwner({
             claims: user?.identity.ownershipEntityRefs ?? [],
           }),
         );
       }
   
       if (isPermission(request.permission, azureDevOpsPullRequestDashboardReadPermission)) {
         return { result: AuthorizeResult.ALLOW };
       }
   
       return { result: AuthorizeResult.ALLOW };
     }
   }

New frontend system alpha support

If you use the new frontend system you can enable the plugin as a feature

1. Install the frontend package if you did not already

   Copy

   yarn --cwd packages/app add @backstage-community/plugin-azure-devops

2. Register the feature

   Copy

   // packages/app-next or packages/app src App.tsx
   import azureDevOpsPlugin from '@backstage-community/plugin-azure-devops';
   
   export const app = createApp({
     features: [
       catalogPlugin,
       catalogImportPlugin,
       userSettingsPlugin,
       azureDevOpsPlugin,
     ],
   });

You can also enable feature discovery in app config

app:
  packages: all