RHDH Plugin Catalog Index Extraction

Use this skill to extract plugin information from the RHDH plugin catalog index OCI image (quay.io/rhdh/plugin-catalog-index).

Prerequisites

• skopeo must be installed and available in PATH
• python3 with json and base64 modules (standard library)

Step 1: Determine the Catalog Index Tag

The tag matches the RHDH version from package.json in the rhdh repo:

TAG=$(jq -r '.version' package.json)
# e.g. 1.10.0

The full image reference is quay.io/rhdh/plugin-catalog-index:${TAG}.

Step 2: Download and Extract the Image

TMPDIR=$(mktemp -d)
EXTRACT_DIR="${TMPDIR}/extracted"
mkdir -p "$EXTRACT_DIR"

# Download (must override os/arch since it's a linux/amd64 image)
skopeo copy --override-os=linux --override-arch=amd64 \
  "docker://quay.io/rhdh/plugin-catalog-index:${TAG}" \
  "dir:${TMPDIR}/catalog-index"

# Extract all layers
for blob in "${TMPDIR}/catalog-index/"*; do
  [ -f "$blob" ] && tar -xf "$blob" -C "$EXTRACT_DIR" 2>/dev/null || true
done

Step 3: Inspect Extracted Contents

After extraction, the key files are:

${EXTRACT_DIR}/
├── dynamic-plugins.default.yaml    # Default plugin list (bundled/pre-installed plugins)
└── catalog-entities/
    └── extensions/
        ├── collections/            # Plugin collection groupings
        ├── packages/               # Individual package entities (one YAML per package)
        │   ├── <plugin-name>.yaml  # Contains: dynamicArtifact, version, appConfigExamples
        │   └── ...
        └── plugins/                # Plugin entities (one YAML per plugin group)
            ├── <plugin-name>.yaml  # Contains: description, categories, highlights, spec.packages
            └── ...

Key fields in package entity files (packages/*.yaml):

• spec.dynamicArtifact — Full OCI reference to use in dynamic-plugins.yaml package field
• spec.version — Plugin version
• spec.backstage.role — One of: frontend-plugin, backend-plugin, backend-plugin-module
• spec.backstage.supportedVersions — Compatible Backstage version
• spec.appConfigExamples — Array of example configurations including pluginConfig wiring
• spec.partOf — Plugin group name (links related frontend/backend/modules together)

Finding a specific plugin:

# List all available packages
ls "${EXTRACT_DIR}/catalog-entities/extensions/packages/"

# Search for a plugin by name
ls "${EXTRACT_DIR}/catalog-entities/extensions/packages/" | grep <plugin-name>

# Read plugin details including OCI reference and default config
cat "${EXTRACT_DIR}/catalog-entities/extensions/packages/<plugin-name>.yaml"

Finding related packages (frontend + backend + modules):

Look at spec.partOf in any package YAML to find the group name, then find all packages with the same partOf value:

grep -l "partOf:" "${EXTRACT_DIR}/catalog-entities/extensions/packages/"*.yaml | \
  xargs grep -l "<group-name>"

Step 4: Get Plugin Metadata from OCI Annotations

For additional metadata (not in catalog entities), inspect the OCI image annotations directly:

skopeo inspect --no-tags --raw \
  "docker://<oci-image-reference>" | \
  python3 -c "
import sys, json, base64
manifest = json.load(sys.stdin)
b64 = manifest.get('annotations', {}).get('io.backstage.dynamic-packages', '')
if b64:
    print(json.dumps(json.loads(base64.b64decode(b64).decode('utf-8')), indent=2))
"

This returns the io.backstage.dynamic-packages annotation containing package name, version, backstage role, and plugin relationships.

Step 5: List Available Tags for a Plugin

skopeo list-tags "docker://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/<plugin-image-name>"

Tags follow the pattern: bs_<backstage-version>__<plugin-version> (e.g., bs_1.45.3__2.3.5).

Step 6: Create dynamic-plugins.yaml

Use the spec.dynamicArtifact as the package value and spec.appConfigExamples[].content as the pluginConfig:

plugins:
  - package: <spec.dynamicArtifact value>
    disabled: false
    pluginConfig:
      <content from spec.appConfigExamples>

Notes

• The dynamic-plugins.default.yaml in the image root only contains pre-installed/bundled plugins. Additional plugins (like scorecard) are only available via the catalog entity files.
• The catalog index image is built from the rhdh-plugin-export-overlays repository.
• Plugin OCI images are hosted at ghcr.io/redhat-developer/rhdh-plugin-export-overlays/.
• Always clean up temp directories after extraction.