Backstage CI/CD Statistics Plugin

Install the frontend package

1. From your repository root, add the plugin to the app package
   Copy

   yarn workspace app add @backstage-community/plugin-cicd-statistics

Provide a CicdStatisticsApi implementation

This plugin does not fetch builds by itself. You must provide an API client that implements CicdStatisticsApi and bind it to cicdStatisticsApiRef.

1. Create a client in your app

   • File path
     Copy

     packages/app/src/plugins/cicdStatisticsApi.ts

   • Code
     Copy

     import {
       CicdStatisticsApi,
       cicdStatisticsApiRef,
       statusTypes,
       ChartTypes,
       FetchBuildsOptions,
       CicdState,
     } from '@backstage-community/plugin-cicd-statistics';
     import {
       FetchApi,
       fetchApiRef,
     } from '@backstage/core-plugin-api';
     import { Entity } from '@backstage/catalog-model';
     
     // Replace the fetch logic with calls to your CI system
     export class MyCicdStatisticsClient implements CicdStatisticsApi {
       constructor(private readonly fetchApi: FetchApi) {}
     
       async getConfiguration(_opts: { entity: Entity }) {
         const chartTypesAllStatuses: Record<string, ChartTypes> = {
           succeeded: ['duration', 'count'],
           failed: ['duration', 'count'],
           running: ['count'],
           aborted: ['count'],
           unknown: ['count'],
           scheduled: ['count'],
           enqueued: ['count'],
           stalled: ['count'],
           expired: ['count'],
         };
     
         return {
           availableStatuses: statusTypes,
           defaults: {
             normalizeTimeRange: true,
             lowercaseNames: true,
             hideLimit: 6,
             collapsedLimit: 10,
             chartTypes: chartTypesAllStatuses as any,
             filterStatus: ['succeeded', 'failed'],
             filterType: 'all',
           },
           formatStageName: (_parents: string[], name: string) => name,
         };
       }
     
       async fetchBuilds(options: FetchBuildsOptions): Promise<CicdState> {
         const {
           entity,
           timeFrom,
           timeTo,
           filterStatus,
           filterType,
           abortSignal,
           updateProgress,
         } = options;
     
         updateProgress(0, 1);
     
         // Example stub
         // Replace this with a call to your CI provider or an internal service
         const response = await this.fetchApi.fetch('/api/cicd-stats', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
             entityRef: `${entity.kind}:${entity.metadata.namespace ?? 'default'}/${entity.metadata.name}`,
             timeFrom,
             timeTo,
             filterStatus,
             filterType,
           }),
           signal: abortSignal,
         });
     
         // Expected structure
         // { builds: Array<Build> }
         const data = await response.json();
     
         updateProgress(1, 1);
         return { builds: data.builds ?? [] };
       }
     }
     
     // Helper for factory wiring
     export const cicdStatisticsApiFactory = {
       api: cicdStatisticsApiRef,
       deps: { fetchApi: fetchApiRef },
       factory: ({ fetchApi }: { fetchApi: FetchApi }) =>
         new MyCicdStatisticsClient(fetchApi),
     };

2. Register the API in your app API registry

   • File path
     Copy

     packages/app/src/apis.ts

   • Code
     Copy

     import { createApiFactory } from '@backstage/core-app-api';
     import { cicdStatisticsApiFactory } from './plugins/cicdStatisticsApi';
     
     export const apis = [
       createApiFactory(cicdStatisticsApiFactory),
     ];

3. Ensure your app uses the apis export

   • File path
     Copy

     packages/app/src/App.tsx

   • Code
     Copy

     import React from 'react';
     import { createApp } from '@backstage/core-app-api';
     import { apis } from './apis';
     import { FlatRoutes } from '@backstage/core-app-api';
     import { Route } from 'react-router';
     import { AppRouter } from './components/AppRouter';
     
     const app = createApp({
       apis,
     });
     
     const AppProvider = app.getProvider();
     const AppRoutes = app.getRoutes();
     
     export default function App() {
       return (
         <AppProvider>
           <AppRouter>
             <FlatRoutes>
               {AppRoutes}
               <Route path="/" element={null} />
             </FlatRoutes>
           </AppRouter>
         </AppProvider>
       );
     }

Add the UI to the Catalog entity page

The component reads the current entity via useEntity. Add it to the Software Catalog entity page so users can see charts for each entity.

1. Import the component
   • File path
     Copy

     packages/app/src/components/catalog/EntityPage.tsx

   • Code
     Copy

     import React from 'react';
     import {
       EntityLayout,
       EntitySwitch,
       isKind,
       hasCatalogProcessingErrors,
       EntityProcessingErrorsPanel,
     } from '@backstage/plugin-catalog';
     import { EntityAboutCard } from '@backstage/plugin-catalog';
     import { EntityCicdStatisticsContent } from '@backstage-community/plugin-cicd-statistics';
     
     const isComponent = isKind('Component');
     
     export const EntityPage = () => (
       <EntitySwitch>
         <EntitySwitch.Case if={hasCatalogProcessingErrors}>
           <EntityProcessingErrorsPanel />
         </EntitySwitch.Case>
     
         <EntitySwitch.Case if={isComponent}>
           <EntityLayout>
             <EntityLayout.Route path="overview" title="Overview">
               <EntityAboutCard />
             </EntityLayout.Route>
     
             {/* New tab for CI CD statistics */}
             <EntityLayout.Route path="ci-cd" title="CI CD">
               <EntityCicdStatisticsContent />
             </EntityLayout.Route>
           </EntityLayout>
         </EntitySwitch.Case>
     
         <EntitySwitch.DefaultCase>
           <EntityLayout>
             <EntityLayout.Route path="overview" title="Overview">
               <EntityAboutCard />
             </EntityLayout.Route>
           </EntityLayout>
         </EntitySwitch.DefaultCase>
       </EntitySwitch>
     );

Wire the plugin object in legacy apps

This step is optional for most apps, but safe. It helps keep plugin features discoverable.

1. Add the plugin object to the app setup
   • File path
     Copy

     packages/app/src/App.tsx

   • Code
     Copy

     import { createApp } from '@backstage/core-app-api';
     import { cicdStatisticsPlugin } from '@backstage-community/plugin-cicd-statistics';
     import { apis } from './apis';
     
     const app = createApp({
       apis,
       plugins: [
         cicdStatisticsPlugin,
       ],
     });

Backend setup

There is no backend package for this plugin. You do not need to install anything for the legacy backend system. You do not need to install anything for the new backend system.

Your CicdStatisticsApi implementation can call your own backend service or your CI provider. The plugin only needs the data. How you fetch it is up to you.