Version: Early Access

Adding Release Plugin Backstage Backend System

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 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.

Run the following command from the Backstage root directory.

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

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
  });
}

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));

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.

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:

Run the following command from the Backstage root directory:

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

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();

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.

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);
// ...

Known Issue

For release versions ≤ 24.1.12 and 24.3.x, clicking on a workflow prompts you to enter login credentials to display the logo for each workflow. It is a known issue and it will fixed in upcoming releases.

Support Information

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

Tested Version:

	Backstage	@backstage/create-app
Legacy Backend System	1.23.0	0.5.11
New Backend system	1.26.0	0.5.14

Before You Begin​

Installing and Configuring the Backend Plugin - Legacy Backend System​

For New Backend System​

Permissions​

Permission Policy​

Known Issue​

Support Information​