Home

The rhdh-plugin-export-overlays repository serves as a metadata and automation hub for managing dynamic plugins for Red Hat Developer Hub (RHDH). It allows discovering, curating, packaging and publishing third-party backstage plugins as OCI images that can be loaded dynamically in RHDH.

Basic concepts

• Workspaces: A workspace is a directory in this repository that represents a logical group of plugins from a single upstream source, typically a monorepo (e.g., backstage/community-plugins/workspaces/adr). Each workspace directory must contain:
  • plugins-list.yaml: A list of the specific packages to export from the source monorepo.
  • source.json: Metadata about the upstream source, including its repository URL (repo), a specific git tag/commit (repo-ref), and its directory structure (repo-flat).
• Overriding plugin sources: Overlays vs Patches:
  • Overlay: Adds or replaces entire files at the plugin level during packaging. This is the preferred method for additive, non-invasive changes.
  • Patch: Applies line-level edits before packaging. Use for precise changes and place the patch file at the workspace root.
• Lifecycle: The process is automated as much as possible: Discover → Propose PR per workspace/branch → Optionally manually enhance with overlay/patch → Build test OCI images → Validate in RHDH → Merge branch → Publish final images.

Target Backstage Compatibility

The automation in this repository strictly enforces Backstage version compatibility. A workspace is only merged and published if its sources are compatible with the Backstage version targeted by the given branch (main or release-x.y).

However, in cases of a "best-effort" compatibility match (workspace backstage version lower than the RHDH target backstage version) where automated checks cannot guarantee compatibility, you can manually assert it after thorough testing. To do this, add a backstage.json file in the workspace folder (workspaces/<workspace-name>/backstage.json) within your PR. This file will override the version compatibility check during the export process, signaling that you have manually validated the plugin against the target Backstage version.

The following badge shows a list of workspaces that contain at least one plugin that is not compatible with the Backstage version targeted by the main branch.

Core policies and conventions

• Sources: Upstream workspaces sources must be from GitHub.
• Branches: Long-lived release-x.y branches track RHDH release lines.
• Reproducibility: For reproducibility, source.json files should reference an immutable git tag or commit in the repo-ref field.
• Image Tagging: Test images (from PRs) are tagged <pr_number>_<plugin_version>. Final images (after merge) are tagged bs_<backstage_version>__<plugin_version>.