Skip to main content
Version: Release 24.3

Adding Release Plugin to Your Backstage IDP

Before You Begin​

Ensure that you have installed the Backstage application. If not, you can follow the Getting Started guide on Backstage to create one. Once you have the Backstage application installed, you can proceed with installing the plugins.

Installing and Configuring the Frontend Plugin​

The frontend plugin needs to be added to your application. To do so:

  1. Run the following command from the Backstage root directory:

yarn --cwd packages/app add @digital-ai/plugin-dai-release

  1. Add Active Releases to your Backstage.

a. Add the DaiReleasePage extension to your App.tsx to include the ReleaseHomePage component exported from the plugin. For example,

// In packages/app/src/App.tsx
import {DaiReleasePage} from '@digital-ai/plugin-dai-release';
const routes = (
     <FlatRoutes>
        {/* ...other routes */}
        <Route path="/dai-release" element={<DaiReleasePage/>}/>

b. Add Digital.ai Release to your app sidebar.

i) In packages/app/src/components/Root/Root.tsx

import '@digital-ai/dot-icons/index.css';

export const activeReleaseIcon = () => {
return <span className="dot-icon">
<i className="icon-release"/>
</span>
}

ii) Add the following to display in the dropdown menu.

In packages/app/src/components/Root/Root.tsx

<SidebarItem icon={ReleaseSvgIcon} onClick={() => {}} text="digital.ai Release">
<SidebarSubmenu title="Release">
<SidebarSubmenuItem
title="Active releases"
to="dai-release"
icon={activeReleaseIcon}
/>
</SidebarSubmenu>
</SidebarItem>
  1. Add Release template to your Backstage.

a. Add the DaiTemplatePage extension to your App.tsx to include the ReleaseHomePage component exported from the plugin. For example,

   // In packages/app/src/App.tsx
import {DaiTemplatePage} from '@digital-ai/plugin-dai-release';

const routes = (
     <FlatRoutes>
        {/* ...other routes */}
        <Route path="/dai-template" element={<DaiTemplatePage/>}/>

b. Add Digital.ai Template to your app sidebar.

/ In packages/app/src/components/Root/Root.tsx
import '@digital-ai/dot-icons/index.css';

export const activeReleaseIcon = () => {
return <span className="dot-icon">
<i className="icon-release"/>
</span>
}

c. Add the following to display in the dropdown menu.


<SidebarItem icon={ReleaseSvgIcon} onClick={() => {}} text="digital.ai Release">
<SidebarSubmenu title="Templates">
<SidebarSubmenuItem
title="Templates"
to="dai-release"
icon={templateIcon}
/>
</SidebarSubmenu>
</SidebarItem>

Installing and Configuring the Backend Plugin - Legacy Backend System​

It is a simple plugin that makes API requests to Digital.ai Release.

important

If you're using new Backstage backend system, refer to Backstage New Backend System.

  1. Run the following command from the Backstage root directory.
yarn --cwd packages/backend add @digital-ai/plugin-dai-release-backend
  1. Create a plugin file for deploy backend in the packages/backend/src/plugins/ directory.
// packages/backend/src/plugins/dai-release.ts
import { createRouter } from '@digital-ai/plugin-dai-release-backend';
import { Router } from 'express';
import type { PluginEnvironment } from '../types';
export default function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return createRouter({
        logger: env.logger,
    config: env.config,
    permissions: env.permissions
  });
}
  1. Modify your backend router to expose the APIs for Release backend.
// packages/backend/src/index.ts
import daiRelease from './plugins/dai-release';
// ...
async function main() 
  // ...
  // Add this line under the other lines that follow the useHotMemoize pattern
  const daiReleaseEnv = useHotMemoize(module, () => createEnv('dai-release'));
  // ...
  // Insert this line under the other lines that add their routers to apiRouter in the same way
  apiRouter.use('/dai-release', await daiRelease(daiReleaseEnv));

  1. Configure the Release instance by adding the following to your app-config.yaml files.

tip

Release plugin supports multi instance integration option. All values are mandatory, and if any of the keys or values are missing, the application fails to start.

For single instance setup:

daiRelease:
   instances:
      - name: {name-of-first-instance} #
        host: {host-of-first-instance} #http://digital-ai-1.release.com:4516
        token: {token-of-first-instance}

For multi instance setup:

daiRelease:
   instances:
      - name: {name-of-first-instance} #
        host: {host-of-first-instance} #http://digital-ai-1.release.com:4516
        token: {token-of-first-instance}
      - name: {name-of-second-instance}
        host: {host-of-second-instance} #http://digital-ai-2.release.com:4516
        token: {token-of-second-instance}

Configuration Details:

  • name: is used to display in UI for choosing instance.
  • host: is your release application host.
  • token: You must set an environment variable for your release application's API token. Create an account with read permissions and use the token from that account.
  1. Run yarn start-backend from the repo root directory.

For New Backend System​

The Dai Release backend plugin has support for the new backend system. To add the new backend system:

  1. Run the following command from the Backstage root directory:
yarn --cwd packages/backend add @digital-ai/plugin-dai-release-backend

  1. In your packages/backend/src/index.ts make the following changes:
import { createBackend } from '@backstage/backend-defaults';

  const backend = createBackend();

  // ... other feature additions

+ backend.add(import('@digital-ai/plugin-dai-release-backend'));

  backend.start();

  1. Configure the Release instance by adding the following to your app-config.yaml files.

tip

Release plugin supports multi instance integration option. All values are mandatory, and if any of the keys or values are missing, the application fails to start.

For single instance setup:

daiRelease:
   instances:
      - name: {name-of-first-instance} #
        host: {host-of-first-instance} #http://digital-ai-1.release.com:4516
        token: {token-of-first-instance}

For multi instance setup:

daiRelease:
   instances:
      - name: {name-of-first-instance} #
        host: {host-of-first-instance} #http://digital-ai-1.release.com:4516
        token: {token-of-first-instance}
      - name: {name-of-second-instance}
        host: {host-of-second-instance} #http://digital-ai-2.release.com:4516
        token: {token-of-second-instance}

Configuration Details:

  • name: is used to display in UI for choosing instance.
  • host: is your release application host.
  • token: You must set an environment variable for your release application's API token. Create an account with read permissions and use the token from that account.

Permissions​

The DAI Release plugin is compatible with the permissions framework. The following sections provide guidance on how to use it, assuming the permissions framework is already configured and operational.

Note: These sections are intended as guidance and are completely optional. The dai-release plugin works with the permission framework enabled and does not does not require any specific policy setup.

Secure Sidebar Option​

To use the permission framework to secure the Digital.ai Release sidebar option do the following:

  1. Add the @backstage/plugin-dai-release-common package to your frontend app:
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-dai-release-common
  1. Open the packages/app/src/components/Root/Root.tsx file, and add imports after all the existing import statements:
import { daiReleaseViewPermission } from '@digital-ai/plugin-dai-release-common';
import { RequirePermission } from '@backstage/plugin-permission-react';

Then make the following changes:

+   <RequirePermission
+     permission={daiReleaseViewPermission}
+     errorPage={<></>}>
+     <SidebarItem icon={ReleaseSvgIcon} to="dai-release" text="Digital.ai Release" />
+   </RequirePermission>

Secure the dai-release Route​

To use the permission framework to secure the dai-release route do the following:

  1. Add the @backstage/plugin-dai-release-common package to your frontend app (skip this step if you've done already):
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-dai-release-common
  1. Open the packages/app/src/App.tsx file, and add import after all the existing import statements:
import { daiReleaseViewPermission } from '@digital-ai/plugin-dai-release-common';

Then make the following change:

+   <Route path="/dai-release"
+     element={
+     <RequirePermission permission={daiReleaseViewPermission}>
+       <DaiReleasePage/>
+     </RequirePermission>
+     }
+   />

Permission Policy​

Here is an example permission policy for legacy backend system that you might use to secure the Digital.ai Release plugin.

// packages/backend/src/plugins/permission.ts

class TestPermissionPolicy implements PermissionPolicy {
  async handle(request: PolicyQuery): Promise<PolicyDecision> {
    if (isPermission(request.permission, daiReleaseViewPermission)) {
      if (
        user?.identity.ownershipEntityRefs.includes(
          'group:default/release-admins',
        )
      ) {
        return { result: AuthorizeResult.ALLOW };
      }
      return { result: AuthorizeResult.DENY };
    }

    return { result: AuthorizeResult.ALLOW };
  }
}

To use this policy ensure to add the @backstage/plugin-dai-release-common package to your backend plugin. Run the following command:

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-dai-release-common

Also, add these imports:

import { daiReleaseViewPermission } from '@digital-ai/plugin-dai-release-common';

Note: The group "group:default/release-admins" is simply an example and might not exist. You can point this to any group you have in your catalog instead.

Here is an example permission policy for new backend system that you might use to secure the Digital.ai Release plugin.

// packages/backend/src/index.ts

import { createBackendModule } from '@backstage/backend-plugin-api';
import {
  PolicyDecision,
  AuthorizeResult,
  isPermission
} from '@backstage/plugin-permission-common';
import {
  PermissionPolicy,
  PolicyQuery,
} from '@backstage/plugin-permission-node';
import { policyExtensionPoint } from '@backstage/plugin-permission-node/alpha';
import {
    catalogConditions,
    createCatalogConditionalDecision,
} from '@backstage/plugin-catalog-backend/alpha';
import {
    daiReleaseViewPermission
} from "@digital-ai/plugin-dai-release-common";
import {
    catalogEntityDeletePermission,
} from '@backstage/plugin-catalog-common/alpha';

// ...
class CustomPermissionPolicy implements PermissionPolicy {
  async handle(
      request: PolicyQuery,
      user?: BackstageIdentityResponse,
  ): Promise<PolicyDecision> {

    if (isPermission(request.permission, daiReleaseViewPermission)) {
      if (
          user?.identity.ownershipEntityRefs.includes(
              'group:default/backstage-admins',
          )
      ) {
        return { result: AuthorizeResult.ALLOW };
      }
      return { result: AuthorizeResult.DENY };
    }

    return {
      result: AuthorizeResult.ALLOW,
    };
  }
}

const customPermissionBackendModule = createBackendModule({
  pluginId: 'permission',
  moduleId: 'custom-policy',
  register(reg) {
    reg.registerInit({
      deps: { policy: policyExtensionPoint },
      async init({ policy }) {
        policy.setPolicy(new CustomPermissionPolicy());
      },
    });
  },
});

backend.add(customPermissionBackendModule);
// ...

Support Information​

Plugin: @digital-ai/plugin-dai-release-backend

Tested Version:

Backstage@backstage/create-app
Legacy Backend System1.23.00.5.11
New Backend system1.26.00.5.14