--- name: overlay description: Manage RHDH plugins in the overlay repository (rhdh-plugin-export-overlays). Onboard, update, maintain, and triage plugins in the Extensions Catalog. --- This skill uses the orchestrator CLI. **Set up first:** ```bash RHDH=..\/rhdh\/scripts\/rhdh ``` **Verify environment:** ```bash $RHDH ``` If `needs_setup: true`, run `$RHDH doctor` before proceeding. <\/cli_setup> 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. <\/principle> 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. <\/principle> 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). <\/principle> 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. <\/principle> <\/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.** <\/intake> ### 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.** <\/routing> For status checks, use the CLI: ```bash $RHDH workspace list # List all workspaces $RHDH workspace status # Check specific workspace ``` Or run direct commands: ```bash # 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 "" ``` <\/inline_status_check> For triggering publish on one or more PRs: ```bash REPO="redhat-developer\/rhdh-plugin-export-overlays" # Single PR gh pr comment --repo $REPO --body "\/publish" # Check if publish already ran gh pr view --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 `references\/github-reference.md` (in rhdh skill) for full patterns. <\/inline_publish_trigger> **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\/` <\/reference_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> | Template | Purpose | |----------|---------| | workspace-files.md | source.json, plugins-list.yaml, backstage.json | <\/templates_index> ### 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>