overlay

Name: overlay
Author: redhat-developer

31installs31forks

How to install overlay?

redhat-developer/rhdh-skill/overlay

$npx -y skills add redhat-developer/rhdh-skill --skill overlay

Installs into the current project.

Summary

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,

Files · 1

View on GitHub

SKILL.md

1	<cli_setup>
2	This skill uses the orchestrator CLI. Set up first:
3
4	```bash
5	RHDH=../rhdh/scripts/rhdh
6	```
7
8	Verify environment:
9
10	```bash
11	$RHDH
12	```
13
14	If `needs_setup: true`, run `$RHDH doctor` before proceeding.
15	</cli_setup>
16
17	<essential_principles>
18
19	<principle name="overlay_repo_pattern">
20	All plugin exports go through [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays).
21	Each plugin lives in a workspace folder with `source.json` + `plugins-list.yaml`.
22	CI handles the actual export - we define the configuration.
23	</principle>
24
25	<principle name="version_fields">
26	Two Backstage version fields serve different purposes:
27	- `source.json` → `repo-backstage-version` = upstream's actual version
28	- `backstage.json` → `version` = our override for RHDH compatibility
29
30	Never confuse these. CI validates the source.json value matches upstream.
31	</principle>
32
33	<principle name="test_with_pr_artifacts">
34	Always test with PR artifacts before merge using rhdh-local.
35	OCI format: `oci://<registry>/<image>:pr_<number>__<version>!<package-name>`
36	Success = plugin loads and attempts API calls (auth errors are expected without real credentials).
37	</principle>
38
39	<principle name="copy_similar_workspaces">
40	When stuck, find a similar workspace and copy its patterns.
41	AWS plugins → copy from `aws-ecs/` or `aws-codebuild/`
42	Community plugins → copy from `backstage/`
43	Check existing PRs for structure examples.
44	</principle>
45
46	</essential_principles>
47
48	<intake>
49	## Identify Task
50
51	What overlay task would you like to do?
52
53	### Plugin Owner Tasks
54
55	For contributors managing their own plugin(s)
56
57	1. Onboard a new plugin — Add upstream plugin to Extensions Catalog
58	2. Update plugin version — Bump to newer upstream commit/tag
59	3. Check plugin status — Verify health and compatibility
60	4. Fix build failure — Debug CI/publish issues
61
62	### Core Team Tasks
63
64	For COPE/Plugins team managing the overlay repository
65
66	5. Triage overlay PRs — Prioritize open PRs by criticality
67	6. Analyze specific PR — Check assignment, compatibility, merge readiness
68	7. Trigger publish — Add /publish comment to PR(s)
69
70	Wait for response before proceeding.
71	</intake>
72
73	<routing>
74	### Plugin Owner Routes
75
76	\| Response \| Workflow \|
77	\|----------\|----------\|
78	\| 1, "onboard", "add", "new plugin", "import" \| `workflows/onboard-plugin.md` \|
79	\| 2, "update", "bump", "upgrade", "version" \| `workflows/update-plugin.md` \|
80	\| 3, "status", "check", "health" \| Run inline status checks \|
81	\| 4, "fix", "debug", "failure", "error" \| `workflows/fix-build.md` \|
82
83	### Core Team Routes
84
85	\| Response \| Workflow \|
86	\|----------\|----------\|
87	\| 5, "triage", "prioritize", "backlog" \| `workflows/triage-prs.md` \|
88	\| 6, "analyze", "check PR", "PR #" \| `workflows/analyze-pr.md` \|
89	\| 7, "publish", "trigger" \| Run inline publish trigger \|
90
91	After reading the workflow, follow it exactly.
92	</routing>
93
94	<inline_status_check>
95	For status checks, use the CLI:
96
97	```bash
98	$RHDH workspace list # List all workspaces
99	$RHDH workspace status <name> # Check specific workspace
100	```
101
102	Or run direct commands:
103
104	```bash
105	# Recent CI runs
106	gh run list --repo redhat-developer/rhdh-plugin-export-overlays --limit 5
107
108	# Open PRs for workspace
109	gh pr list --repo redhat-developer/rhdh-plugin-export-overlays --search "<name>"
110	```
111
112	</inline_status_check>
113
114	<inline_publish_trigger>
115	For triggering publish on one or more PRs:
116
117	```bash
118	REPO="redhat-developer/rhdh-plugin-export-overlays"
119
120	# Single PR
121	gh pr comment <number> --repo $REPO --body "/publish"
122
123	# Check if publish already ran
124	gh pr view <number> --repo $REPO --json statusCheckRollup \
125	--jq '.statusCheckRollup[] \| select(.name \| contains("publish"))'
126	```
127
128	Guards before triggering:
129
130	1. PR is open (not closed/merged)
131	2. No `do-not-merge` label
132	3. Publish check not already successful
133
134	See `../rhdh/references/github-reference.md` for full patterns. If unavailable, use standard `gh` CLI patterns.
135	</inline_publish_trigger>
136
137	<reference_index>
138	Overlay repo patterns: references/overlay-repo.md
139	CI feedback interpretation: references/ci-feedback.md
140	Metadata format: references/metadata-format.md
141	PR label priorities: references/label-priority.md
142	RHDH Local testing: references/rhdh-local.md
143
144	For GitHub/JIRA patterns: See `../rhdh/references/` (if unavailable, use standard `gh` / `acli` patterns)
145	</reference_index>
146
147	<workflows_index>
148
149	### Plugin Owner Workflows

People who liked this also viewed

6 picks

Type

overlay

31installs31forks

View on GitHub

How to install overlay?

redhat-developer/rhdh-skill/overlay

$npx -y skills add redhat-developer/rhdh-skill --skill overlay

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<cli_setup>
2	This skill uses the orchestrator CLI. Set up first:
3
4	```bash
5	RHDH=../rhdh/scripts/rhdh
6	```
7
8	Verify environment:
9
10	```bash
11	$RHDH
12	```
13
14	If `needs_setup: true`, run `$RHDH doctor` before proceeding.
15	</cli_setup>
16
17	<essential_principles>
18
19	<principle name="overlay_repo_pattern">
20	All plugin exports go through [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays).
21	Each plugin lives in a workspace folder with `source.json` + `plugins-list.yaml`.
22	CI handles the actual export - we define the configuration.
23	</principle>
24
25	<principle name="version_fields">
26	Two Backstage version fields serve different purposes:
27	- `source.json` → `repo-backstage-version` = upstream's actual version
28	- `backstage.json` → `version` = our override for RHDH compatibility
29
30	Never confuse these. CI validates the source.json value matches upstream.
31	</principle>
32
33	<principle name="test_with_pr_artifacts">
34	Always test with PR artifacts before merge using rhdh-local.
35	OCI format: `oci://<registry>/<image>:pr_<number>__<version>!<package-name>`
36	Success = plugin loads and attempts API calls (auth errors are expected without real credentials).
37	</principle>
38
39	<principle name="copy_similar_workspaces">
40	When stuck, find a similar workspace and copy its patterns.
41	AWS plugins → copy from `aws-ecs/` or `aws-codebuild/`
42	Community plugins → copy from `backstage/`
43	Check existing PRs for structure examples.
44	</principle>
45
46	</essential_principles>
47
48	<intake>
49	## Identify Task
50
51	What overlay task would you like to do?
52
53	### Plugin Owner Tasks
54
55	For contributors managing their own plugin(s)
56
57	1. Onboard a new plugin — Add upstream plugin to Extensions Catalog
58	2. Update plugin version — Bump to newer upstream commit/tag
59	3. Check plugin status — Verify health and compatibility
60	4. Fix build failure — Debug CI/publish issues
61
62	### Core Team Tasks
63
64	For COPE/Plugins team managing the overlay repository
65
66	5. Triage overlay PRs — Prioritize open PRs by criticality
67	6. Analyze specific PR — Check assignment, compatibility, merge readiness
68	7. Trigger publish — Add /publish comment to PR(s)
69
70	Wait for response before proceeding.
71	</intake>
72
73	<routing>
74	### Plugin Owner Routes
75
76	\| Response \| Workflow \|
77	\|----------\|----------\|
78	\| 1, "onboard", "add", "new plugin", "import" \| `workflows/onboard-plugin.md` \|
79	\| 2, "update", "bump", "upgrade", "version" \| `workflows/update-plugin.md` \|
80	\| 3, "status", "check", "health" \| Run inline status checks \|
81	\| 4, "fix", "debug", "failure", "error" \| `workflows/fix-build.md` \|
82
83	### Core Team Routes
84
85	\| Response \| Workflow \|
86	\|----------\|----------\|
87	\| 5, "triage", "prioritize", "backlog" \| `workflows/triage-prs.md` \|
88	\| 6, "analyze", "check PR", "PR #" \| `workflows/analyze-pr.md` \|
89	\| 7, "publish", "trigger" \| Run inline publish trigger \|
90
91	After reading the workflow, follow it exactly.
92	</routing>
93
94	<inline_status_check>
95	For status checks, use the CLI:
96
97	```bash
98	$RHDH workspace list # List all workspaces
99	$RHDH workspace status <name> # Check specific workspace
100	```
101
102	Or run direct commands:
103
104	```bash
105	# Recent CI runs
106	gh run list --repo redhat-developer/rhdh-plugin-export-overlays --limit 5
107
108	# Open PRs for workspace
109	gh pr list --repo redhat-developer/rhdh-plugin-export-overlays --search "<name>"
110	```
111
112	</inline_status_check>
113
114	<inline_publish_trigger>
115	For triggering publish on one or more PRs:
116
117	```bash
118	REPO="redhat-developer/rhdh-plugin-export-overlays"
119
120	# Single PR
121	gh pr comment <number> --repo $REPO --body "/publish"
122
123	# Check if publish already ran
124	gh pr view <number> --repo $REPO --json statusCheckRollup \
125	--jq '.statusCheckRollup[] \| select(.name \| contains("publish"))'
126	```
127
128	Guards before triggering:
129
130	1. PR is open (not closed/merged)
131	2. No `do-not-merge` label
132	3. Publish check not already successful
133
134	See `../rhdh/references/github-reference.md` for full patterns. If unavailable, use standard `gh` CLI patterns.
135	</inline_publish_trigger>
136
137	<reference_index>
138	Overlay repo patterns: references/overlay-repo.md
139	CI feedback interpretation: references/ci-feedback.md
140	Metadata format: references/metadata-format.md
141	PR label priorities: references/label-priority.md
142	RHDH Local testing: references/rhdh-local.md
143
144	For GitHub/JIRA patterns: See `../rhdh/references/` (if unavailable, use standard `gh` / `acli` patterns)
145	</reference_index>
146
147	<workflows_index>
148
149	### Plugin Owner Workflows

People who liked this also viewed

6 picks

Type