feat(skills): add rhdh-must-gather-helm-bump skill and script

[nickboldt]

Summary

Adds the rhdh-must-gather-helm-bump skill (skills/ci/) and bundled scripts/bump-must-gather-helm.py to propagate a Helm CLI version bump across:

Repo	What the skill changes
redhat-developer/rhdh-must-gather	Makefile HELM_VERSION, CGW artifacts.lock.yaml or vendor/helm/, Stage 2a/2b on Containerfile and .rhdh/docker/Containerfile
gitlab.cee.redhat.com/rhidp/rhdh	Mirror helm-related files into distgit/containers/rhdh-must-gather/; regenerate the hermetic distgit Containerfile; patch must-gather Tekton prefetch; write sync/upstream_SHA_rhdh-must-gather

This is the Helm CLI in the must-gather image, not the RHDH Helm chart (oci://quay.io/rhdh/chart). The script does not commit, push, or open a PR/MR.

Catalog: registered under skills/ci/ in catalog.json, marketplace, and /ask-rhdh routes.

https://redhat.atlassian.net/browse/RHIDP-16046

What the script does

Preview (ungated): --check probes CGW and prints helm_version= / mode=cgw|vendor. --dry-run prints the planned writes without touching trees. Approval to preview is not approval to apply.

Apply (after /mutation-gate; upstream and distgit/Tekton as separate operations):

1. Choose install path by probing upstream hack/check-helm-binary-available.sh (same probe for --check and apply, including --skip-upstream):
   • CGW (preferred): hack/update-helm-lockfile.sh → Konflux generic prefetch on distgit root → Stage 2a active
   • Vendor fallback: hack/update-vendor.sh helm → gomod prefetch on vendor/helm → Stage 2b active
2. Flip Stage 2a/2b bidirectionally (doc-only comments stay commented) on upstream Containerfile, .rhdh/docker/Containerfile, and the regenerated distgit Containerfile.
3. Sync into distgit: Makefile, artifacts.lock.yaml, entire hack/, .rhdh/docker/Containerfile, entire vendor/ (on CGW, omit/delete vendor/helm; keep websocat etc.). Does not copy upstream root Containerfile onto hermetic distgit.
4. Regenerate distgit Containerfile from .rhdh/docker/Containerfile, preserving RHDH_MUST_GATHER_VERSION and the Brew/Konflux ENV SUMMARY= / LABEL footer. Increments release="N" → N+1 and the konflux.additional-tags version-release suffix with a numeric boundary (2.0-1 → 2.0-2, 2.0-10 → 2.0-11 not 2.0-20).
5. Patch Tekton prefetch for must-gather only: .tekton/rhdh-must-gather-2-{pull,push}.yaml and must-gather.prefetch_input in .tekton-templates/components.yaml (generic vs gomod). Other components.yaml entries are left untouched.
6. Write sync/upstream_SHA_rhdh-must-gather from a committed upstream HEAD. Refuses to pin a dirty HEAD (--allow-dirty still does not write a SHA from uncommitted work).

--skip-upstream syncs distgit + Tekton + SHA only. --skip-downstream bumps upstream only.

Discovery and guards

• --parent-dir finds must-gather (1-must-gather, …) and midstream (4-rhdh, rhdh-downstream, rhidp-rhdh) only when the candidate has distgit/containers/rhdh-must-gather (skips a GitHub rhdh clone).
• Requires hack/check-helm-binary-available.sh on upstream; missing bash / rsync is a hard error.
• git status failures (fatal: not a git repository, etc.) die instead of looking clean.
• Requires Python 3.9+, bash, curl, git, rsync.

Agent workflow (in SKILL.md)

1. Confirm --to against Helm releases.
2. Resolve checkouts.
3. --check + --dry-run (preview).
4. Apply only after /mutation-gate.
5. Review git diff + references/verification.md (unit tests, Konflux, E2E triage including Helm 4 OCI stdout).
6. Commit / PR or MR only when asked, again through /mutation-gate (Jira via /rhdh-jira-link).

References: install-paths (CGW vs vendor, tarball layout), tekton-prefetch, verification, helm4-notes.

Related upstream work: rhdh-must-gather#284 (CGW binary), rhdh-must-gather#282 (vendored fallback).

Tests

tests/unit/test_must_gather_helm_bump.py (invoked via sys.executable):

• Real --to bump off the 4.2.3 fixture (lockfile/vendor stubs update HELM_VERSION)
• CGW sync omits vendor/helm, keeps websocat, scopes prefetch to must-gather, updates pull and push PLRs
• Vendor mode flips 2a→2b; a second case flips 2b back to 2a
• --dry-run writes nothing
• release="10" / 2.0-10 → 11 / 2.0-11
• Failed git status, dirty-HEAD SHA refusal, rhdh-downstream discovery, missing CGW probe script
• --skip-upstream --check still reports mode=cgw when upstream CGW is available (stale distgit vendor/helm does not win)

Test plan

• uv run pytest tests/unit/test_must_gather_helm_bump.py
• uv run pytest tests/unit/test_skill_catalog.py
• --check / --dry-run smoke test against local must-gather + midstream checkouts

Generated-by: cursor

[Fortune-Ndlovu]

LGTM

[schultzp2020]

The CGW vs vendor split, and editing only must-gather's prefetch, are the right idea. I'd tighten the apply path before this runs against rhidp/rhdh. --check and --skip-upstream can pick different modes, 2.0-10 becomes 2.0-20, and a failed git status looks clean. Tests don't hit those cases. On Windows the new file fails on shebang exec (WinError 193) before rsync is involved.

Comments below are the hunks I'd change. While you're there: don't write upstream_SHA from a dirty HEAD; require hack/check-helm-binary-available.sh and turn a missing bash/rsync into die(); run tests via sys.executable and actually bump --to off the 4.2.3 fixture (the lockfile stubs are no-ops); cover --dry-run, push.yaml, and 2b back to 2a. Same skills/ci/... path is in the script docstring. PR body still names bump-must-gather-helm.sh.

[schultzp2020]

The category folder is gone after install, so an agent that copies this Usage block misses the script and starts editing Tekton by hand. rhdh-yarn-bump uses a placeholder for that reason.

Suggested change

	SKILL=skills/ci/rhdh-must-gather-helm-bump # under rhdh-skill checkout
	SKILL=<this skill's directory>

[schultzp2020]

--check and --dry-run can stay ungated. The next line writes two other working trees. /mutation-gate calls that a write. rhdh-base-images gates the apply; rhdh-prow-trigger says a dry-run is not approval to execute. Completion below currently treats the real run as done before anyone signed off.

Suggested change

	4. Run `--dry-run`, then the script without `--dry-run`.
	5. Review `git diff` in **both** repos.
	6. Run every verification gate — read [references/verification.md](references/verification.md).
	7. Commit / PR·MR only when the user asks.
	3. Run `--check` and `--dry-run`. That pair is the preview.
	4. Apply only after `/mutation-gate` approval, with upstream and distgit/Tekton as separate operations. Approval to dry-run is not approval to write.
	5. Review `git diff` in both repos, then the gates in [references/verification.md](references/verification.md).
	6. Commit / PR or MR only when the user asks, again through `/mutation-gate`.

[schultzp2020]

If upstream is the sync source, probe it on apply the same way you do for --check. --skip-upstream currently looks at distgit: leftover vendor/helm (the test fixture always has this) plus an old lock for a different version becomes mode=vendor, while --check still prints mode=cgw. Then you copy a CGW lockfile and set gomod prefetch.

Suggested change

	if upstream is not None and (not skip_upstream or check_only):
	if upstream is not None:

[schultzp2020]

check=False plus "empty stdout means clean" treats fatal: not a git repository as success. That path is rc 128 with empty stdout, then distgit still gets written. Tests always pass --allow-dirty, so this never runs.

Suggested change

	result = subprocess.run(
	["git", "-C", str(path), "status", "--porcelain"],
	capture_output=True,
	text=True,
	check=False,
	)
	if result.stdout.strip():
	result = subprocess.run(
	["git", "-C", str(path), "status", "--porcelain"],
	capture_output=True,
	text=True,
	check=False,
	)
	if result.returncode != 0:
	die(
	f"{label} is not a git repository or git status failed ({path}): "
	f"{result.stderr.strip() or 'unknown error'}"
	)
	if result.stdout.strip():

[schultzp2020]

replace("2.0-1", "2.0-2") also rewrites 2.0-10. Same hole in the no-version regex. Add a test with release="10" / 2.0-10; the fixture only covers 1 -> 2.

Suggested change

	if version:
	footer = footer.replace(f"{version}-{current}", f"{version}-{next_n}")
	else:
	footer = re.sub(
	rf'(konflux\.additional-tags="[^\"]*-){re.escape(current)}',
	rf"\g<1>{next_n}",
	footer,
	)
	footer = footer.replace(f'release="{current}"', f'release="{next_n}"')
	if version:
	footer = re.sub(
	rf"{re.escape(version)}-{re.escape(current)}(?![0-9])",
	f"{version}-{next_n}",
	footer,
	)
	else:
	footer = re.sub(
	rf'(konflux\.additional-tags="[^\"]*-){re.escape(current)}(?![0-9])',
	rf"\g<1>{next_n}",
	footer,
	)

[schultzp2020]

--parent-dir never looks for rhdh-downstream, which is the name /rhdh-context uses. rhdh is the GitHub clone. Validate fails (no silent write), but a sibling GitLab checkout is never tried. Stronger still: only accept a candidate that has distgit/containers/rhdh-must-gather.

Suggested change

	found = discover_repo(parent, "4-rhdh", "rhdh", "rhidp-rhdh")
	found = discover_repo(parent, "4-rhdh", "rhdh-downstream", "rhidp-rhdh")