rhdh-plugin-midstream-propagate

RHDH プラグイン → オーバーレイ → カタログへの反映

redhat-developer/rhdh-plugins で修正または機能を追加した後の3段階の流れです。

1. 変更セット（changeset）を含めて rhdh-plugins を更新し、マージされて新しいパッケージが npmjs.com に公開されるまで待ちます（例：@red-hat-developer-hub/backstage-plugin-app-defaults 0.0.3 と、同時に公開されるその他のパッケージ）。
2. overlays リポジトリ（rhdh-plugin-export-overlays）を更新し、上記の変更に関連する Version Packages PR のコミット SHA を取得します。
3. その SHA から該当する変更を取得し、rhdh-plugin-catalog に反映します。overlay-repo/、workspaces/、および そのワークスペースだけをフルクローンした場合に sync-midstream.sh が変更するその他のパスを更新し、更新ファイルを適用する MR を作成します。その際、.tekton/ の関連 PLR も適切なタグ（例：2.0.0--0.0.3）に更新します。

build/ci/sync-midstream.sh --force-clone <workspace> よりも、**必要な部分だけを変更する（surgical）**カタログ MR を優先してください（数分で済むのに対し、フルクローンとエクスポートには長時間かかります）。エクスポート、plugin_builds アノテーション、またはワークスペース変換の再生成が必要な場合に限り、対象を絞った --force-clone を使用してください。

リポジトリと設定

Step	Repo	Config key
1	redhat-developer/rhdh-plugins	repos.plugins
2	redhat-developer/rhdh-plugin-export-overlays	repos.overlay
3	gitlab.cee.redhat.com/rhidp/rhdh-plugin-catalog	repos.catalog

チェックアウト先を確認するには、名前を指定して /rhdh-context を呼び出し、表示されたパスを読み取ります。代わりに CLI を直接実行するには、RHDH にそのスキルの scripts/rhdh ラッパーを設定し、ドット記法のキーを使用します："$RHDH" --json config get repos.<key> | jq -r '.data.value'（references/catalog-surgical-update.md を参照）。カタログの MR には、gitlab.cee.redhat.com を対象に glab を使用してください（gitlab.com ではありません）。

PR/MR を作成する前に、Jira キーを確認してください。課題リンクを添付するには、名前を指定して /rhdh-jira-link スキルを呼び出します。PR または MR 自体を作成するには、名前を指定して /rhdh-pr-create スキルを呼び出します。どちらのスキルもインストールされていない場合に限り、gh / glab を直接使用してください。

---

Step 1 — rhdh-plugins（＋ changeset → npm）

Changeset の作成に従い、changeset を含めて修正を取り込み、ボットの Version Packages PR をマージし、そのリリースに含まれるすべてのパッケージが npmjs.com に公開されるまで待ちます。

**Step 2 に進む前の確認事項：**公開された npm のバージョンが Version Packages の更新内容と一致していること。npm view <pkg>@<ver> gitHead の値が Version Packages のマージ SHA と一致していること。

任意：名前を指定して /rhdh-pr-create スキルを呼び出し、rhdh-plugins のビルド、changeset、PR を作成できます。

---

Step 2 — overlays（source.json → Version Packages SHA）

npm への公開後、workspaces/<ws>/ でメタデータの同期に従います。source.json の repo-ref を（修正コミットではなく）Version Packages のマージ SHA に設定し、repo-backstage-version を合わせ、同じリリースで公開されたすべてのパッケージについて、metadata/*.yaml のバージョンと dynamicArtifact の OCI タグを更新します。

カタログ作業に進む前に overlays の PR をマージしてください。カタログのミッドストリームは、この変更の反映後の overlays main（またはリリースブランチ）を対象にする必要があります。

注： /rhdh-overlay は、一般的な source.json の更新を含む overlays リポジトリを管理します。ワークスペースを編集するには、名前を指定して呼び出してください。この手順で加わる制約は、repo-ref が Version Packages の SHA でなければならないことです。依頼に Version Packages、カタログへの昇格、またはミッドストリームが含まれる場合は、通常のオーバーレイ更新よりこのスキルを優先してください。

---

ステップ 3 — カタログの部分更新による MR 作成

編集前に references/catalog-surgical-update.md を読んでください（パス、設定の取得、PLR の再生成、対象を限定した同期フラグの正式な参照元です）。

目標：すべてのワークスペースをクローンせずに、1 つのワークスペースについて sync-midstream.sh --force-clone '<ws>' で更新されるファイルと同じファイル一式を更新します。

推奨（部分更新）

1. overlays の main から overlay-repo/workspaces/<ws>/ を同期します（source.json、plugins-list.yaml、metadata/、存在する場合は overlays/patches）。
2. $SHA にある upstream の差分を workspaces/<ws>/ に適用します。最低限、ルートの package.json / yarn.lock（lockfile を所有するツリー）と、プラグインの package.json のバージョン更新を適用します。Version Packages の変更が lock／メタデータのみではない場合は、プラグインのソースにも範囲を広げてください。plugins/<name>/ 内だけにある lock／解決ピンは適用しないでください。
3. plugin_builds/<ws>/*.json の registryReference タグをそろえます（quay.io/rhdh/...:<rhdh>--<pluginVer>、例：2.0.0--0.0.3）。
4. 関連する .tekton/ の PLR／Containerfile を更新します。
   • konflux.additional-tags → <xy>--<ver>,<x.y.z>--<ver>（例：2.0--0.0.3,2.0.0--0.0.3）
   • DESCRIPTION のプラグインバージョン部分
   • 判明している場合は、UPSTREAM_REPO に overlays ツリーの SHA
   • または、.tekton/updatePLRs.sh で該当する PLR を再生成します（参照先：ネスト型では --path '<ws>/plugins/<plugin>'、フラット型では --package。source.json の repo-flat に基づいて判断します）。
5. 名前付きスキル /rhdh-pr-create を呼び出すか、CEE GitLab に対して glab を使ってカタログ MR を作成します。本文には関連パッケージのバージョンを記載してください。このスキルが glab で直接送信する本文を作成する場合は、書き込みゲートの前に、完全なタイトルと本文に対して、flavored レジスターで /prose-editing を 1 回呼び出します。バージョン、SHA、パッケージ名、見出し、リンク、コマンドはそのまま保持してください。最終的な作成者が /rhdh-pr-create の場合は、事実を渡し、編集はしないでください。このスキルが 1 回の文章校正を担当します。

.tekton の担当範囲： このスキルが担当するのは、昇格対象のワークスペースに対する部分更新のカタログ MR に含まれる、ワークスペースごとの PLR と Containerfile のタグ更新のみです。カタログ全体の PipelineRun の完全な再生成は /rhdh-konflux-tasks の担当です。このスキルを名前で呼び出し、ここからストリーム全体を再生成しないでください。

フォールバック（対象を限定した同期）

エクスポート／アノテーション／update-workspace.js の変換が必要な場合は、references/catalog-surgical-update.md に記載されたコマンドを使ってください（ここで別のフラグの組み合わせを考案しないでください）。差分（ピン、lock、バージョン）が判明している場合は、部分更新を優先してください。

---

外部への書き込み

ブランチのプッシュ、コメント、overlays PR の作成、カタログ MR の作成は外部への書き込みです。名前付きスキル mutation-gate を呼び出し、このスキルが定めるゲートに従ってください。ここでゲートの内容を繰り返さないでください。プラグインを昇格したいという依頼は、意図を示すものであり、特定のプッシュへの承認ではありません。

---

チェックリスト

• rhdh-plugins の変更に changeset が含まれており、Version Packages がマージ済み
• npm パッケージが公開済み。gitHead == Version Packages の SHA
• overlays の repo-ref とメタデータのバージョン／OCI タグが更新され、マージ済み
• カタログの overlay-repo/workspaces/<ws>/ が overlays と一致
• カタログの workspaces/<ws>/ が、yarn.lock を所有するルートで $SHA を反映（必要に応じて lock／解決設定／バージョンを更新）
• plugin_builds/ と .tekton/ のタグが新しいプラグインバージョン（x.y.z--<pluginVer>）と一致
• CEE GitLab でカタログ MR を作成済み。Jira にリンク済み

例（RHIDP-16097 / app-defaults）

ステップ	成果物
1	rhdh-plugins の修正 + changeset → Version Packages → @…/[email protected]（gitHead 18f4229…）
2	workspaces/app-defaults/source.json とメタデータを更新する overlays PR
3	overlay-repo/…/app-defaults とワークスペースのルートの lock ピンを同期するカタログ MR（部分更新。--force-clone は使用しない）

完了

上記のチェックリストのすべての項目にチェックが入り、各ステップが直前のステップの報告が正しいことに依存せず、単独で検証できたらチェーンは完了です。

公開されたパッケージのバージョンと、それらが解決される SHA、overlays の PR と catalog の MR の URL、それらが関連付けられている Jira キー、catalog の変更がピンポイントで行われたのか、スコープを限定した --force-clone にフォールバックしたのかを報告してください。未完了の項目（マージ待ち、進行中の npm publish、/rhdh-konflux-tasks に引き継いだストリーム全体の PipelineRun 再生成、または実施すると述べたものの承認されていない外部への書き込み）があれば、すべて明記してください。