checking-devops-prerequisites

DevOps の前提条件の確認

すべての DevOps Center テストスキルで共通するチェックです。クエリやシステム呼び出しを行う前に、これらのチェックを実行してください。失敗した場合は、平易なメッセージを表示して、ユーザーが解決するまで停止してください。環境を検証せずに書き込みを行ってはいけません。

API バージョン： DevOps のテストで使用するシステム呼び出しは、すべて Salesforce API v67.0（最低要件）を対象とします。

重要： DevOps Center のデータ（パイプライン、ステージ、テストスイート、実行）は Salesforce 組織内にあります。ローカルリポジトリ内にはありません。ファイルシステムでパイプライン設定を検索してはいけません。必ず sf data query または sf api request rest を使って組織にクエリしてください。

他のスキルでの利用方法

DevOps のテストスキルはすべて、最初にこのスキルを読み込み、前提条件 1～4 を順に実行します。前提条件 5（ステージ）は、呼び出し元のスキルが特定のパイプラインステージを操作する場合（テストスイートの実行／再実行、同期、ゲートの設定、テストスイートのマッピング）のみ実行します。呼び出し元のスキルには、解決済みの doce-org-alias、pipelineId、および該当する場合は stageId を渡し、そのスキルのコマンドで使用します。

ユーザーに尋ねずに、DevOps Center の組織エイリアスを解決してください。ただし、本当に曖昧な場合は除きます。

1. ユーザーのメッセージで組織エイリアスが指定されている場合は、それを使用します。
2. それ以外の場合は、デフォルトの組織を使用します（sf org display --json。--target-org は指定しません）。
3. デフォルトの組織に DevopsPipeline レコードがない場合（前提条件 4 が失敗した場合）のみ、「DevOps Center の組織エイリアスを指定してください」と尋ねます。

---

前提条件 1 — Salesforce 組織：ログインが有効

sf org list --json

result.nonScratchOrgs、result.scratchOrgs、または result.sandboxes に "connectedStatus": "Connected" のエントリが少なくとも 1 つあることを確認します。

• 成功： Connected の組織が少なくとも 1 つある
• 失敗： 組織が一覧にない、またはすべて接続されていない状態である

失敗した場合：「認証済みの Salesforce 組織が見つかりません。ターミナルで sf org login web --alias <your-alias> を実行してから、もう一度お試しください。」

---

前提条件 2 — Agentforce DX プラグインがインストール済み

sf plugins --json

name に plugin-agent、agentforce、または einstein が含まれるプラグインエントリ（大文字と小文字は区別しません）を探します。

• 成功： プラグインが見つかった
• 失敗： 該当するエントリがない

失敗した場合：「Agentforce DX Plugin がインストールされていません。sf plugins install @salesforce/plugin-agent を実行し、IDE を再起動してから、もう一度お試しください。」

---

前提条件 3 — DevOps Center 組織が認証済み

sf org display --target-org <doce-org-alias> --json

"connectedStatus" が "Connected" であることを確認します。

• 成功： Connected
• 失敗： セッションの有効期限切れ、またはエラー

失敗した場合：「DevOps Center 組織のセッションの有効期限が切れています。再認証するには、sf org login web --alias <doce-org-alias> を実行してください。」

---

前提条件 4 — パイプラインの特定

sf data query \
  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
  --target-org <doce-org-alias> \
  --json

• 成功（1 件）： 自動的に使用します。尋ねてはいけません。
• 成功（複数件）： ユーザーがすでにパイプラインを指定している場合は、名前で照合します。それ以外の場合は、番号付きリストを表示して尋ねます。

  Found <N> pipelines:
  1. <Name>
  2. <Name>
  Which pipeline would you like to work with?
  

• 失敗（レコードなし）：「DevOps Center のパイプラインが見つかりません。DevOps Testing Skills を使用する前に、DevOps Center でプロジェクトとパイプラインを作成してください。」
• 失敗（未対応のオブジェクト）：「<doce-org-alias> に DevOps Center がインストールされていないようです。正しい組織を指定しているか確認してください。」

---

前提条件 5 — パイプラインステージの特定（条件付き）

呼び出し元のスキルが特定のステージを操作する場合にのみ実行します。

ユーザーのメッセージですでにステージが指定されている場合（例：「Integration」、「Staging」、「Production」）は、その名前をそのまま使用します。再度尋ねてはいけません。Id を検索します。

sf data query \
  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
  --target-org <doce-org-alias> --json

ステージが指定されていない場合にのみ、一覧全体を取得して、どのステージかを尋ねます。

sf data query \
  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
  --target-org <doce-org-alias> --json

続けて、「どのパイプラインステージを操作しますか？」と尋ねます。組織エイリアスを尋ねてはいけません。ステージはパイプラインから名前で解決します。

• 成功： ステージの Id と Name が確認済み
• 保留： 呼び出し元のスキルで必要になるまで不要

---

エラー処理

エラー条件	応答
sf org list が完全に失敗する	"Salesforce CLI に接続できませんでした。sf がインストールされ、PATH に設定されていることを確認してください。"
sf org display が認証エラーを返す	わかりやすい再認証手順を表示します。生のエラーは表示しないでください。
DevopsPipeline のクエリが 5xx で失敗する	"DevOps Center の組織でサーバーエラーが発生しています。数分後にもう一度お試しください。"
いずれかのチェックで予期しない例外が発生する	"前提条件の確認中に問題が発生しました。エラー：［わかりやすい概要］。もう一度試すか、手動で解決して、準備ができたらお知らせください。"

生の API エラー、スタックトレース、JSON エラーペイロードをユーザーに表示しないでください。

注意点

問題	解決方法
DevopsPipeline のクエリ結果が空	対象の組織に DevOps Center がインストールされていないか、組織エイリアスが間違っています。ユーザーに確認を依頼してください
DevopsWorkItem sObject がサポートされていない	WorkItem（名前空間なし）を使用してください。この組織バージョンでの正しい API 名です
レビュートリガーはステージレベルではなくパイプラインレベルです	TriggerType = 'Review' および RelatedRecordId = <pipelineId> の DevopsPipelineStageTrigger をクエリしてください
Connect API の testSuites が ?stageId= で空を返す	?triggerId=<reviewTriggerId> を使用してください。stageId が機能するのはステージレベルトリガーの場合のみです
sf plugins に agentforce がない	インストール済みのプラグインは @salesforce/plugin-agent です。plugin-agent も照合対象にしてください