rhdh-plugin-export-utils
Utilities for exporting backstage plugins as dynamic plugins for installation in Red Hat Developer Hub
Actions
export-dynamic
Exports plugins as dynamic plugin archives. This should be run after the override-sources action in order to support per-plugin source overlays, or if patch modifications are needed.
Usage:
- name: Export Dynamic Plugins
uses: ./export-dynamic
with:
plugins-root: plugins
plugins-file: ${{ github.workspace }}/plugins-list.yaml
destination: ${{ github.workspace }}/archives
Key Features:
- Exports plugins as dynamic plugin packages
- Handles both frontend and backend plugins
- Optional container image packaging
- Empty-OCI gates (see below) so empty exports are not pushed to ghcr.io
Empty OCI payload gates
Before packaging or publishing, export-dynamic validates that each plugin has an installable payload:
- After
plugin export — dist-dynamic/package.json must exist, the package name must end with -dynamic, and a dist entry must be present: backend index.cjs.js / index.esm.js / index.js (or main under dist/), or frontend remoteEntry.js / mf-manifest.json.
- After
plugin package, before push — the local image must have a non-empty io.backstage.dynamic-packages annotation (or, if the annotation cannot be read, a non-empty layer index.json).
Failures are recorded in the failed-exports output and the export-dynamic action/step fails (non-zero exit). The image is not pushed and is not listed in published-exports. This applies to export-only runs as well as package/push — an empty dist-dynamic fails before packaging.
If a workspace fails these checks, fix the overlay plugins-list.yaml (export args, --embed-package, missing packages) and re-run publish. Do not rely on midstream or weekly registry scans as the primary gate.
Helpers live in export-dynamic/validate-plugin-payload.sh; unit tests: bash export-dynamic/validate-plugin-payload.test.sh. Image checks require skopeo and exit if it is missing. The export action and the publish workflow install it when an image repository prefix is set.
override-sources
Applies patches and source overlays to modify plugin sources before export. This should be run before the export-dynamic action.
Features:
- Applies patches from
<overlay-root>/patches/ directory using git apply
- Copies source overlay files from
<overlay-root>/plugins/{plugin-name}/overlay/ directories
- Robust error handling and cleanup
- Ordered patch application (by filename)
- Configurable overlay subfolder name (defaults to "overlay")
Usage:
- name: Override Sources
uses: ./override-sources
with:
overlay-root: ${{ github.workspace }}/my-overlay-repo
workspace-root: .
Inputs:
overlay-root: Absolute path to the overlay root directory (expects patches/ and plugins/ subdirectories)
workspace-root: Directory to apply changes to (defaults to ".")
source-overlay-folder-name: Name of subfolder within each plugin directory containing overlay files (defaults to "overlay")
Outputs:
patches-applied: Number of patches applied
source-overlay-applied: Whether source overlay files were copied
validate-metadata
Validates catalog metadata files against plugin package.json files to ensure consistency. This should be run after the export-dynamic action.
Features:
- Validates
packageName corresponds to a plugin from plugins-list.yaml
- Validates
version matches the plugin's package.json version
- Validates OCI reference format in
dynamicArtifact (tag and repository prefix)
- Validates
backstage.supportedVersions matches major.minor of dist-dynamic/package.json
- Reports detailed errors to GitHub workflow summary
- Provides JSON output for downstream workflow consumption
Usage:
- name: Validate Catalog Metadata
uses: ./validate-metadata
with:
overlay-root: ${{ github.workspace }}/overlay-repo/workspaces/my-workspace
plugins-root: ${{ github.workspace }}/source-repo/workspaces/my-workspace
target-backstage-version: 1.42.5
image-repository-prefix: ghcr.io/my-org/my-repo # Optional
Inputs:
overlay-root: Absolute path to the overlay workspace folder containing metadata/ and plugins-list.yaml
plugins-root: Absolute path to the source plugins folder containing plugin directories with package.json files
target-backstage-version: Target Backstage version for validating OCI tag format
image-repository-prefix: Repository prefix for validating OCI reference format (optional)
Outputs:
validation-passed: Whether the metadata validation passed (true/false)
validation-errors: JSON array of validation errors (see validate-metadata/README.md for format details)
validation-error-count: Number of validation errors found
Workflow Example
jobs:
export-plugins:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v6
- name: Override Sources (apply patches and overlays)
uses: ./override-sources
with:
overlay-root: ${{ github.workspace }}/overlay-repo
workspace-root: .
- name: Export Dynamic Plugins
uses: ./export-dynamic
with:
plugins-root: plugins
plugins-file: ${{ github.workspace }}/plugins-list.yaml
destination: ${{ github.workspace }}/archives
- name: Validate Catalog Metadata
uses: ./validate-metadata
with:
overlay-root: ${{ github.workspace }}/overlay-repo
plugins-root: ${{ github.workspace }}/plugins