overlay

name

overlay

description

Manages the rhdh-plugin-export-overlays repository — onboards plugins to the Extensions Catalog, updates plugin versions, fixes overlay build failures, triages and analyzes PRs, triggers publishes, and manages plugin workspaces. Use when working with overlays, importing plugins, debugging CI, checking PRs, bumping versions, or mentions "Extensions Catalog", "overlay build failed", "plugin registry", "overlay PR", "overlay doctor", "plugin import", "add plugin to catalog", "onboard plugin", or "plugin workspace".

<cli_setup> This skill uses the orchestrator CLI. Set up first:

RHDH=../rhdh/scripts/rhdh

Verify environment:

$RHDH

If needs_setup: true, run $RHDH doctor before proceeding. </cli_setup>

<essential_principles>

All plugin exports go through [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays). Each plugin lives in a workspace folder with `source.json` + `plugins-list.yaml`. CI handles the actual export - we define the configuration. Two Backstage version fields serve different purposes: - `source.json` → `repo-backstage-version` = upstream's **actual** version - `backstage.json` → `version` = our **override** for RHDH compatibility

Never confuse these. CI validates the source.json value matches upstream.

Always test with PR artifacts before merge using rhdh-local. OCI format: `oci:///:pr___!` Success = plugin loads and attempts API calls (auth errors are expected without real credentials). When stuck, find a similar workspace and copy its patterns. AWS plugins → copy from `aws-ecs/` or `aws-codebuild/` Community plugins → copy from `backstage/` Check existing PRs for structure examples.

</essential_principles>

## Identify Task

What overlay task would you like to do?

Plugin Owner Tasks

For contributors managing their own plugin(s)

1. Onboard a new plugin — Add upstream plugin to Extensions Catalog
2. Update plugin version — Bump to newer upstream commit/tag
3. Check plugin status — Verify health and compatibility
4. Fix build failure — Debug CI/publish issues

Core Team Tasks

For COPE/Plugins team managing the overlay repository

5. Triage overlay PRs — Prioritize open PRs by criticality
6. Analyze specific PR — Check assignment, compatibility, merge readiness
7. Trigger publish — Add /publish comment to PR(s)

Wait for response before proceeding.

### Plugin Owner Routes

Response	Workflow
1, "onboard", "add", "new plugin", "import"	workflows/onboard-plugin.md
2, "update", "bump", "upgrade", "version"	workflows/update-plugin.md
3, "status", "check", "health"	Run inline status checks
4, "fix", "debug", "failure", "error"	workflows/fix-build.md

Core Team Routes

Response	Workflow
5, "triage", "prioritize", "backlog"	workflows/triage-prs.md
6, "analyze", "check PR", "PR #"	workflows/analyze-pr.md
7, "publish", "trigger"	Run inline publish trigger

After reading the workflow, follow it exactly.

<inline_status_check> For status checks, use the CLI:

$RHDH workspace list              # List all workspaces
$RHDH workspace status <name>     # Check specific workspace

Or run direct commands:

# Recent CI runs
gh run list --repo redhat-developer/rhdh-plugin-export-overlays --limit 5

# Open PRs for workspace
gh pr list --repo redhat-developer/rhdh-plugin-export-overlays --search "<name>"

</inline_status_check>

<inline_publish_trigger> For triggering publish on one or more PRs:

REPO="redhat-developer/rhdh-plugin-export-overlays"

# Single PR
gh pr comment <number> --repo $REPO --body "/publish"

# Check if publish already ran
gh pr view <number> --repo $REPO --json statusCheckRollup \
  --jq '.statusCheckRollup[] | select(.name | contains("publish"))'

Guards before triggering:

1. PR is open (not closed/merged)
2. No do-not-merge label
3. Publish check not already successful

See ../rhdh/references/github-reference.md for full patterns. If unavailable, use standard gh CLI patterns. </inline_publish_trigger>

<reference_index> Overlay repo patterns: references/overlay-repo.md CI feedback interpretation: references/ci-feedback.md Metadata format: references/metadata-format.md PR label priorities: references/label-priority.md RHDH Local testing: references/rhdh-local.md

For GitHub/JIRA patterns: See ../rhdh/references/ (if unavailable, use standard gh / acli patterns) </reference_index>

<workflows_index>

Plugin Owner Workflows

Workflow	Purpose
onboard-plugin.md	Full 6-phase process to add new plugin
update-plugin.md	Bump to newer upstream version
fix-build.md	Debug and resolve CI failures

Core Team Workflows

Workflow	Purpose
triage-prs.md	Prioritize open PRs by criticality
analyze-pr.md	Deep-dive on single PR (assignment, compat, readiness)
doctor.md	Environment setup guidance
</workflows_index>

<templates_index>

Template	Purpose
workspace-files.md	source.json, plugins-list.yaml, backstage.json
</templates_index>

<success_criteria>

Plugin Owner Success

• Plugin workspace created with correct structure
• CODEOWNERS entry added for the workspace
• CI passes (/publish succeeds)
• Plugin tested locally with rhdh-local
• PR merged to overlay repo
• (Recommended) Activity logged via $RHDH log add

Core Team Success

• PR backlog prioritized with actionable next steps
• Stale PRs identified with suggested owners
• Publish triggered on PRs needing it
• Compatibility issues flagged before merge
• (Recommended) Triage session logged, follow-ups tracked via $RHDH todo </success_criteria>