Plugin Metadata

The plugin metadata utilities handle loading and injecting plugin configurations from Package CRD metadata files. This enables automatic configuration of dynamic plugins during deployment.

How It Works

Plugin metadata is stored in metadata/*.yaml files alongside your plugin source code. These files follow the Package CRD format and contain spec.appConfigExamples with the plugin's default configuration.

workspaces/<plugin-name>/
├── metadata/                        # Plugin metadata files
│   ├── plugin-frontend.yaml         # Frontend plugin metadata
│   └── plugin-backend.yaml          # Backend plugin metadata
├── e2e-tests/                       # Your test project
│   └── tests/config/
│       └── dynamic-plugins.yaml     # Your plugin config (optional)
└── plugins/                         # Plugin source code

During deployment, the package reads these metadata files and:

• Auto-generates a complete config if dynamic-plugins.yaml doesn't exist
• Injects metadata into existing plugins if dynamic-plugins.yaml exists

When Metadata Handling is Enabled

Metadata handling is enabled by default for:

• Local development
• PR builds in CI

Metadata handling is disabled when:

• RHDH_SKIP_PLUGIN_METADATA_INJECTION is set
• JOB_NAME contains periodic- (nightly builds)

Basic Usage

Check If Enabled

import { shouldInjectPluginMetadata } from "rhdh-e2e-test-utils/utils";

if (shouldInjectPluginMetadata()) {
  console.log("Metadata handling is enabled");
}

Auto-Generate Configuration

When your dynamic-plugins.yaml doesn't exist, generate a complete config from all metadata files:

import { generateDynamicPluginsConfigFromMetadata } from "rhdh-e2e-test-utils/utils";

const config = await generateDynamicPluginsConfigFromMetadata();
// All plugins from metadata/*.yaml are enabled by default

Inject Into Existing Configuration

When you have a dynamic-plugins.yaml, inject metadata for listed plugins:

import { loadAndInjectPluginMetadata } from "rhdh-e2e-test-utils/utils";

const existingConfig = {
  plugins: [
    {
      package: "./dynamic-plugins/dist/my-plugin",
      disabled: false,
      pluginConfig: {
        // Your overrides here
      },
    },
  ],
};

const augmented = await loadAndInjectPluginMetadata(existingConfig);
// Metadata is merged as base, your pluginConfig overrides it

Extract Plugin Name

The utilities support various package reference formats:

import { extractPluginName } from "rhdh-e2e-test-utils/utils";

// All of these extract "my-plugin"
extractPluginName("./dynamic-plugins/dist/my-plugin");
extractPluginName("oci://quay.io/rhdh/my-plugin:1.0.0");
extractPluginName("oci://quay.io/rhdh/my-plugin@sha256:abc123");
extractPluginName("ghcr.io/org/repo/my-plugin:tag");

Parse Metadata Files

For custom handling, you can parse metadata files directly:

import {
  getMetadataDirectory,
  parseAllMetadataFiles,
} from "rhdh-e2e-test-utils/utils";

const metadataDir = getMetadataDirectory();
if (metadataDir) {
  const metadataMap = await parseAllMetadataFiles(metadataDir);

  for (const [pluginName, metadata] of metadataMap) {
    console.log(`Plugin: ${pluginName}`);
    console.log(`  Package: ${metadata.packagePath}`);
    console.log(`  Config:`, metadata.pluginConfig);
  }
}

Deployment Integration

The RHDHDeployment class automatically uses these utilities during deploy():

1. If dynamic-plugins.yaml exists:

   • Merges package defaults + auth config + your config
   • Injects metadata for plugins in your config

2. If dynamic-plugins.yaml doesn't exist:

   • Auto-generates from all metadata files
   • All plugins enabled with default configurations

See Configuration Files for detailed behavior.

OCI URL Generation for PR Builds

When GIT_PR_NUMBER is set (by OpenShift CI), local plugin paths are automatically replaced with OCI URLs pointing to the PR's built artifacts.

How It Works

1. Reads source.json from the workspace directory to get the source repo and commit ref
2. Reads plugins-list.yaml to get the list of plugin paths
3. Fetches each plugin's package.json from the source repo to get the current version
4. Generates OCI URLs in the format:

oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/{plugin-name}:pr_{PR_NUMBER}__{version}

Example

# Local development
- package: ./dynamic-plugins/dist/backstage-community-plugin-tech-radar

# PR build (GIT_PR_NUMBER=1845)
- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-tech-radar:pr_1845__1.13.0

Required Files

For OCI URL generation, your workspace must have these files (generated by CI):

File	Purpose
source.json	Contains repo (GitHub URL) and repo-ref (commit SHA)
plugins-list.yaml	Lists plugin paths (e.g., plugins/tech-radar:)

WARNING

For PR builds, OCI URL generation is strict - deployment will fail if required files are missing or version fetching fails. This ensures PR builds don't silently fall back to local paths.

Environment Variables

Variable	Effect
GIT_PR_NUMBER	Enables OCI URL generation for PR builds
RHDH_SKIP_PLUGIN_METADATA_INJECTION	Disables all metadata handling
JOB_NAME	If contains periodic-, disables metadata handling

See Environment Variables for details.

API Reference

For complete API documentation, see Plugin Metadata API.

For Overlay Repository

If you're writing tests in the rhdh-plugin-export-overlays repository, see Overlay Configuration Files for how plugin metadata and OCI URL generation work in that context.