rhdh-forge

RHDH Forge

Forge を読み取り、書き込み用のペイロードを作成するための単一の場所です。Issue の解析、Issue の取得、ワークスペースの解決、チェックとパイプラインの読み取り、リポジトリのコンテンツの読み取り、そして初めて使う呼び出し元を戸惑わせる gh と glab の挙動は、すべてここに集約されています。そうしなければ、Forge に関わる各スキルが、それぞれ独自の古くなっていくコピーを持つことになります。

このスキルは読み取り専用です。書き込みを実行することはありません。

GitHub の操作には gh を使用します。GitLab の操作 — gitlab.cee.redhat.com 上の rhidp/rhdh と rhidp/rhdh-plugin-catalog — には glab を使用します。GitLab ホストが関係する場合にのみ、glab が必要です。

結果に応じたルーティング

結果	読み込んで従う内容
GitHub Issue の参照を構造化されたコンテキストに変換する	uv run scripts/fetch_issue_context.py <reference> を実行します
ネットワーク呼び出しなしで GitHub または GitLab の参照を解析する	references/issue-context.md
Issue が属するプラグインのワークスペースを解決する	references/issue-context.md
PR の状態、ラベル、担当者、ファイル、またはチェック状態を読み取る	references/gh-cli.md
失敗したチェック、古いチェック、または見つからないチェックについて説明する	references/gh-cli.md
リポジトリまたは PR ブランチからファイルを読み取る	references/gh-cli.md
GitLab の Issue、MR の状態、パイプラインの状態、またはファイルを読み取る	references/glab-cli.md
GitHub のプルリクエスト作成用ペイロードを準備する	references/gh-cli.md、その後、呼び出し元の変更ゲート
GitLab のマージリクエスト作成用ペイロードを準備する	references/glab-cli.md、その後、呼び出し元の変更ゲート
コメント、ラベル、担当者、または /publish 用のペイロードを準備する	references/issue-context.md、その後、呼び出し元の変更ゲート
GitLab のコメント、ラベル、または承認用のペイロードを準備する	references/glab-cli.md、その後、呼び出し元の変更ゲート

呼び出し元は、このスキルを名前で呼び出し、返された内容を利用します。別のスキルからこのスキルのファイルを読み込まないでください。

不変条件

• ここにあるすべてのルートは読み取り専用です。書き込みが必要な呼び出し元には、実行ではなくペイロードを返します。
• 解決済みの名前空間、リポジトリ、番号から Issue、PR、または MR の URL を構築します。ユーザーの生の URL は保持しないでください。フラグメントやクエリ文字列が含まれている可能性があります。
• Jira キーはこのスキルの対象ではありません。抽出して呼び出し元に返し、詳細については呼び出し元から /rhdh-jira-api を呼び出してもらいます。
• gh pr checks と statusCheckRollup はキャッシュされたビューであり、古くなる可能性があります。チェック結果に基づいて操作する前に、gh run list --branch で確認してください。
• GitLab のパイプライン結果はマージリクエストではなくコミットに紐づきます。報告する前に、パイプラインの SHA と MR の head SHA を比較してください。
• 解決できないワークスペースは、解決できないものとして報告します。推測すると、呼び出し元を誤ったリポジトリに誘導してしまいます。
• 認証情報ファイルは決して読み取らないでください。gh auth status または glab auth status が失敗した場合は、停止して利用できない機能を報告します。

変更の境界

参照ファイルに記載されたコマンドパターンはペイロードであり、実行の許可ではありません。このスキルはコマンドを組み立てて、実行せずに返します。これにより、構文を知っているモジュールではなく、ユーザーが判断できる状態を保ちます。

プルリクエスト、マージリクエスト、コメント、ラベル、担当者、レビュー、承認、または /publish の書き込みを行う前に、呼び出し元のスキルは /mutation-gate を呼び出し、その指示に従います。このスキルは、正確な引数ベクトルとシェルで安全に使用できる形式、正規のホストとリポジトリ、対象オブジェクトまたは base ブランチと head ブランチ、該当する場合はタイトル、そして本文ファイルの絶対パスを返します。また、プレビュー用の本文ファイルの内容と、読み取り専用の検証コマンドも返します。書き込みコマンドを実行することはありません。

PR と MR の作成では、タイトルがない場合または複数行の場合、本文ファイルが相対パスまたは読み取り不能な場合、リポジトリを解決できない場合、base ブランチまたは head ブランチが空の場合は拒否します。各値はそれぞれ1つの引数として扱います。タイトルや本文をシェル構文に埋め込んだり、eval を使用したり、本文ファイルをヒアドキュメントに置き換えたりしないでください。

取得、トリアージ、または分析の依頼は、読み取りの意図を示すものです。書き込みの許可にはなりません。

Issue context の出力

scripts/fetch_issue_context.py は、JSON オブジェクトを 1 つだけ出力します。エンベロープはなく、issue のフィールドがドキュメント全体です。

{
  "key": "owner/repo#607",
  "summary": "issue title",
  "source": "github",
  "url": "https://github.com/owner/repo/issues/607",
  "repository": "owner/repo",
  "number": 607,
  "state": "OPEN",
  "labels": [],
  "description": "full issue body",
  "workspace": {"name": null, "strategy": "label"},
  "comments": []
}

key は owner/repo#number、summary は issue のタイトル、state は OPEN または CLOSED、workspace.strategy は label、body、title、package、unresolved のいずれかです。

/rhdh-jira-api は同じ issue 形式を source: jira とともに返します。また、references/glab-cli.md を通じて読み取った GitLab issue は、同じフィールドを source: gitlab とともに設定するため、呼び出し元は形式の違いを条件分岐せずに 3 種類のいずれも処理できます。

未解決のワークスペースは、名前を捏造せず、strategy: unresolved として null のままにしてください。

スクリプトとリファレンス

• scripts/fetch_issue_context.py は、GitHub issue の URL、単独の #number、または owner/repo#number から、そのドキュメントを決定論的に構築します。GitLab issue は代わりに glab で読み取ります。
• references/issue-context.md では、両方の forge の参照解析、フィールド抽出、ワークスペースの解決、ゲート付きの操作ペイロードを説明しています。
• references/gh-cli.md では、gh と jq による読み取りパターン、プルリクエスト作成ペイロード、チェックとワークフロー実行の読み取り、リポジトリコンテンツの読み取り、失敗時の表、オーバーレイリポジトリの /publish ルールを説明しています。
• references/glab-cli.md では、マージリクエスト、パイプライン、リポジトリコンテンツの glab による読み取り、GitLab のマージリクエスト作成ペイロード、GitHub と異なる GitLab のフィールド名、および構築するものの実行しないその他のコマンドを説明しています。

完了条件

フェッチは、JSON に key、summary、source が含まれ、url がリクエストからコピーされず、解決された namespace、リポジトリ、番号から再構築され、workspace.strategy に解決に使用したルールが記載されるか、name: null を伴って unresolved と記載されていれば完了です。チェックの判定は、GitHub では gh run list --branch で確認されるか、GitLab では MR の head SHA に対応するパイプラインで確認されて初めて完了です。gh pr checks または statusCheckRollup の値だけでは、キャッシュされた表示にすぎず、判定とはみなされません。書き込みペイロードは、呼び出し元の変更ゲートに対して未実行のまま返されれば完了です。操作ペイロードには、正確なコマンド、リポジトリ、issue、PR、または MR の番号、head SHA、本文またはラベルを記載します。PR または MR の作成ペイロードには、正規のリポジトリ、正確な base ブランチと head ブランチ、1 行のタイトル、body ファイルの絶対パス、body のプレビュー、引数ベクトル、シェルセーフなコマンド、読み取り専用の検証コマンドを含めます。issue 内で見つかった Jira キーは呼び出し元に報告し、ここでは解決しません。