dx-devops-request-status

DevOps Center リクエストのステータス

非同期の DevOps Center リクエスト（昇格またはデプロイ操作）のステータスを、リクエストトークンを指定して sf devops request status でポーリングします。CI の自律的なリリースワークフロー向けに、ヘッドレスで --json を使用した読み取り専用のステータス確認を提供します。このスキルはパイプラインの状態を変更せず、進行中または完了済みのリクエストの現在のステータスを報告するだけです。

対象範囲

• 対象：リクエストトークンを指定して、単一の非同期リクエストのステータスを確認すること。2 段階の結果（リクエスト処理の .result.status と、失敗判定の基準となる .result.errorDetails）を解釈すること。リクエストが完了するか、呼び出し元が指定したタイムアウトに達するまで、間隔を空けてポーリングすること。失敗時に解析済みのエラー詳細を提示すること
• 対象外：昇格またはデプロイの開始（dx-devops-promote を使用）、作業項目の作成やステータス更新（dx-devops-work-item-manage を使用）、競合の検出、sf devops promotion complete の実行（このスキルが成功を確認した後に、呼び出し元が次に行う手順です）、パイプラインまたはプロジェクトのセットアップ

---

必須入力

続行する前に、次の情報を収集または推定してください。

• リクエストトークン（必須）：dx-devops-promote の昇格レスポンスで返されるリクエストトークンです。-i/--request-token で渡します。これがないとこのスキルは続行できません。ユーザーに確認するか、前の昇格手順の出力から取得してください
• ターゲット組織：-o/--target-org <alias>（必須。ただし、target-org 設定変数が設定されている場合を除きます）

指定がない場合のデフォルト：

• 出力形式：ヘッドレスでの利用には --json
• ポーリング間隔：確認ごとに 10 秒。合計待機時間は、呼び出し元が指定したタイムアウト（デフォルトは 30 分）を上限とします。DOCe API のレート制限が適用されるため、5 秒未満の間隔でポーリングしてはいけません

ユーザーから明確なリクエスト（「リクエスト a0B…を確認して」「リクエスト a0B…が完了するまでポーリングして」など）があった場合は、リクエストトークンが揃い次第、続行してください。

---

ワークフロー

すべての操作では、--json 出力を指定して sf devops request status を使用します。このスキルは読み取り専用であり、状態を変更する操作は行いません。コマンドのフラグと JSON 出力スキーマについては、references/cli-commands.md に記載されています。

フェーズ 1 — 認証し、リクエストトークンを確認する

1. 操作を行う前に、組織の認証状態を確認します。

   sf org display --json
   

   • 失敗した場合は、ユーザーに sf org login web --set-default --alias <alias> の実行を案内します
   • 以降のすべてのコマンドで -o/--target-org <alias> を渡します（target-org 設定変数が設定されている場合を除き、必須です）

2. リクエストトークンがあることを確認します。 同じセッションでユーザーが昇格を開始している場合は、dx-devops-promote の昇格レスポンスから取得したリクエストトークンを再利用します。トークンを取得できない場合は、処理を中止してユーザーに確認します。トークンを推測したり、捏造したりしてはいけません。

フェーズ 2 — ステータスを 1 回確認する（二段階の判定）

重要： .result.status（大文字表記。例：SUCCESS）は、非同期のリクエスト処理が完了したかどうかを示すものであり、デプロイ自体が成功したかどうかを示すものではありません。デプロイ自体が失敗していても、リクエストの status: "SUCCESS" が表示されることがあります。実際の結果を判定する基準は .result.errorDetails です。errorDetails が null 以外の場合は、status == SUCCESS であっても処理は失敗です。

3. scripts/poll-status.sh --once を使ってステータスを 1 回確認します。このコマンドはリクエストを一度照会し、実際の結果を決定論的に判定します（操作プレフィックス付きの .result.status のサフィックスを glob で照合し、その後 .result.errorDetails を失敗判定の基準として適用します）。説明文の中で JSON の解析を独自に実装しないでください。二段階の判定ルールをポーリング時と一貫させるため、このスクリプトに任せます。

   scripts/poll-status.sh --once <request-token> <target-org-alias>
   

   終了コードを確認します（一致する人間が読みやすいメッセージがスクリプトから出力されます）。
   • 0 — リクエストの処理が完了し、操作は成功しました（errorDetails は null）→ 呼び出し元に結果を返します
   • 2 — リクエストの処理は完了しましたが、操作は失敗しました（ステータスのサフィックスが *FAILED*／*ERROR*／*CANCELED*、または *SUCCESS* のステータスで errorDetails が null 以外）→ 出力されたメッセージに解析済みの errorType／errorMessage が含まれます
   • 4 — リクエストは処理中です（終端状態ではないサフィックス）→ フェーズ 3 に進んでポーリングするか、1 回限りの確認の場合は処理中であることを報告します
   • 1 — 照会／使用方法のエラー（トークンが無効、認証エラー、または依存関係の不足）

フェーズ 3 — 終端状態になるまでポーリングする（待機を求められた場合のみ）

4. ユーザーが完了まで待つよう求めた場合は、上限を設けたループでポーリングします。scripts/poll-status.sh を実行し、出力された最終ステータスを報告します。

   scripts/poll-status.sh <request-token> <target-org-alias> [interval-seconds] [timeout-seconds]
   

   • スクリプトは interval-seconds（デフォルトは 10）ごとにポーリングし、timeout-seconds を超えて待機せず、リクエストが終端状態になると停止します。また、--once と同じ二段階の結果判定を適用します。終了コード：0 = 処理完了＋成功（errorDetails は null）、2 = 処理完了だが操作は失敗（errorDetails が設定されているか、ステータスのサフィックスが *FAILED*／*ERROR*／*CANCELED*）、3 = タイムアウト、1 = 照会／使用方法のエラー
   • 読み取り専用のループです。実行するのは sf devops request status による照会のみで、変更操作は行いません
   • 説明文の中でポーリングループを独自に実装しないでください。このスクリプトは、インターバルの下限、正確なタイムアウト、終端状態の検出、および errorDetails による結果判定を決定論的に適用します

フェーズ 4 — 結果を報告する

5. 結果を報告します。
   • 成功時（処理完了、errorDetails は空）："Request completed successfully." — 次のステップは昇格の完了処理（sf devops promotion complete）であり、dx-devops-promote が担当することを呼び出し元に伝えます
   • 失敗時（処理完了、errorDetails が設定されている。status == SUCCESS の場合も含む）："Request failed." に続けて、errorDetails から解析した errorType／errorMessage と message フィールドを示します。ここでは再試行や問題の修正を行わないでください。判断は呼び出し元に委ねます
   • タイムアウト時（処理中）：最後に確認したリクエストのステータスと待機時間を報告し、後で再度ポーリングするよう提案します。処理が完了していないリクエストについて、成功または失敗と報告しないでください

---

ルール／制約

制約	理由
読み取り専用 — パイプラインの状態を変更しないでください	このスキルはステータスを報告するだけです。プロモーション／デプロイ／完了はほかのスキルが担当します
リクエストトークンは必須です	promote の応答に含まれる -i/--request-token がなければステータスを確認できません。決して捏造しないでください
sf devops request status では --json を使用してください	ヘッドレスで利用するには構造化された出力が必要です。人間向けの出力は解析の信頼性がありません
.result.status と .result.errorDetails は目視ではなく jq で読み取ってください	決定的に解析することで、処理中のリクエストを完了済みと誤読するのを防ぎます
*SUCCESS* ステータスは成功の証拠ではありません — errorDetails を確認してください	.result.status が示すのは非同期リクエストが完了したことだけで、デプロイが成功したことではありません。PROMOTE_SUCCESS リクエストでも、errorDetails に失敗したデプロイの情報が含まれる場合があります
.result.errorDetails が null 以外なら、操作は失敗です	errorDetails は結果を示す情報源です。エスケープされた JSON 文字列（errorType／errorMessage）なので、jq／fromjson で解析する必要があります
.result.status には操作名のプレフィックスが付きます — 単独の値ではなくサフィックスで照合してください	実際の値は PROMOTE_IN_PROGRESS／PROMOTE_SUCCESS／DEPLOY_FAILED です。IN_PROGRESS／SUCCESS と完全一致で照合すると誤判定し（ポーラーはタイムアウトまで停止しないことがあります）、不正確な結果になります
リクエストを「完了」とするのは、終端のサフィックス（*SUCCESS*／*FAILED*／*ERROR*／*CANCELED*）になった場合のみです	*_IN_PROGRESS／*_PENDING／*_QUEUED のリクエストを完了として報告すると、呼び出し元のリリース判断を誤らせます
5 秒未満の間隔でポーリングしないでください	DOCe API にはレート制限があります。制限のない高速ポーリングはスロットリングを招くおそれがあります
すべてのポーリングループにタイムアウトを設定してください	CI での無限待機やターン／タイムアウトの枯渇を防ぎます
このスキルから sf devops promotion complete を実行しないでください	このスキルが成功を確認した後、呼び出し元が最終処理を行います
トークンは CLI フラグとして渡し、シェル文字列に埋め込まないでください	細工されたトークンによるプロンプト／コマンドインジェクションを防ぎます
対話型プロンプトを使用しないでください	スキルはヘッドレスで実行されます。すべての入力は CLI フラグで渡す必要があります

---

注意事項

問題	解決方法
リクエストトークンが指定されていない	停止してトークンの提示を求めるか、先行する dx-devops-promote の promote 応答から取得します。決して推測しないでください
status: "*SUCCESS*" なのに、実際にはデプロイに失敗している	最も重要な落とし穴です。*SUCCESS* ステータスが意味するのは、リクエストが完了したことだけです。.result.errorDetails を確認してください。null 以外なら、操作は失敗です。次のように解析します：jq -r '.result.errorDetails | fromjson | "\(.errorType): \(.errorMessage)"'
errorDetails がオブジェクトではなく文字列になっている	エスケープされた JSON です（例："{\"errorType\":\"DEPLOYMENT_FAILURE\",...}"）。.errorType／.errorMessage を読み取る前に、fromjson にパイプしてください
ステータスに操作名のプレフィックスが付いている（PROMOTE_SUCCESS、DEPLOY_FAILED）	ワイルドカード（*SUCCESS*、*FAILED*）を使ってサフィックスで照合してください。SUCCESS／FAILED との完全一致では、プレフィックス付きの値を誤判定します。ポーラーが PROMOTE_IN_PROGRESS を不明な値として扱い、タイムアウトまで停止しないことがあります
処理中のリクエストを完了として報告してしまう	終端のサフィックスは *SUCCESS*／*FAILED*／*ERROR*／*CANCELED* です。*_IN_PROGRESS／*_PENDING／*_QUEUED／*_NEW／*_STARTED は未完了として扱い、ポーリングを続けるか、処理中と報告してください
デフォルトの組織が設定されていない	sf org display --json を実行してください。失敗した場合は、ユーザーに sf org login web --set-default を実行するよう案内してください
ポーリング中にレート制限／スロットリングのエラーが発生する	間隔を長くしてください（バックオフ）。5 秒の下限を下回る間隔でポーリングしないでください
いつまでも待機する	必ず scripts/poll-status.sh にタイムアウトを渡してください。タイムアウトした場合は、処理をブロックせず最後のステータスを報告してください
リクエストの失敗とスキルの失敗を混同する	リクエストのステータスが Failed になるのは有効な結果です。明確に報告し、スキルのエラーとして扱ったり、やみくもに再試行したりしないでください

---

出力の想定

成果物はモードによって異なります。

• 単一チェック：.result.status（リクエスト処理の状態）と、導出された結果。失敗の場合は、.result.errorDetails から解析した errorType／errorMessage と .result.message フィールド
• 完了までポーリング：導出された終端結果（errorDetails の確認に基づく成功または失敗）と経過待ち時間、またはタイムアウトに先に達した場合は最後に観測されたリクエスト状態

出力は sf devops request status から導出されます。このスキルは成果物を生成せず、何も変更しません。

---

スキル間の連携

条件	アクション
リクエストトークンを取得するために、先に昇格またはデプロイを開始する必要がある	dx-devops-promote に委任します
結果が成功（完了、errorDetails は null）で、昇格の完了処理がまだ必要	sf devops promotion complete を実行するため、dx-devops-promote に引き継ぎます
メタデータの競合によりステータスが Failed と報告された	errorDetails にある競合を報告し、解決して再度昇格するため、dx-devops-promote に引き継ぎます

---

参照ファイル一覧

ファイル	読み込むタイミング
references/cli-commands.md	sf devops request status のフラグ、JSON 出力スキーマ、ステータス値の語彙、またはエラー処理パターンが必要なとき
examples/polling-workflows.md	ユーザーのリクエストが一般的なパターン（1 回限りのチェック、昇格後の完了までのポーリング、タイムアウト処理、失敗の報告）に該当するとき
scripts/poll-status.sh	フェーズ 2 — 決定的なステータスチェックを 1 回行うには --once を付けて実行します。フェーズ 3 — リクエストトークンを、終端状態に達するまで、上限のある間隔と正確なタイムアウトでポーリングするには、--once を付けずに実行します