dx-devops-promote

Name: dx-devops-promote
Author: forcedotcom

github.com/forcedotcomクラウド・DevOps1.1k2.3k 回インストール1 日前に更新

dx-devops-promote について

Salesforce の `sf devops` CLI で DevOps Center の昇格フローを進めるスキルです。コマンドラインや CI でのリリース自動化を想定し、必須の検証、準備、必要に応じた結合、昇格、完了を JSON 出力で実行します。

主な機能

01昇格の前提条件を検証
02作業項目を準備
03必要に応じて共通メタデータの項目を結合
04作業項目またはソースステージ全体を昇格
05ターゲットステージで昇格を完了

活用シーン

01作業項目をターゲットステージへ昇格
02ソースステージの承認済み項目を一括昇格
03共通メタデータの作業項目を結合してから昇格

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill dx-devops-promote

インストール後、Claude Code で/dx-devops-promoteを入力して読み込まれたか確認します。

同梱ファイルexamples/promotion-workflows.mdreferences/cli-commands.md

詳細

DevOps Center のプロモーション

DevOps Center のプロモーションワークフロー全体（検証、準備、任意での統合、プロモーション、完了）を実行し、作業項目をリリースパイプライン内で移動します。CI での自律的なリリースワークフロー向けに、ヘッドレスで --json を使用した冪等な操作を提供します。すべてのプロモーションは、必須の検証ステップから始まります。

対象範囲

対象範囲内：プロモーションの前提条件の検証、作業項目の準備、メタデータを共有する作業項目を1つのプロモーションに統合、1つ以上の作業項目またはソースステージ全体のターゲットステージへのプロモーション、プロモーションの完了
対象範囲外：作業項目の作成／ステータス更新（dx-devops-work-item-manage を使用）、競合の検出、既存のプロモーションのステータス確認、パイプラインまたはプロジェクトのセットアップ（別のスキル）

必須入力

実行前に、以下を収集または推定してください。

プロモーションの対象：1つ以上の特定の作業項目、またはソースステージ内の承認済み作業項目すべて
ターゲットステージ ID（すべてのプロモーションコマンドで必須 — validate、prepare、combine、promote、complete）：--target-stage-id — プロモーション先のパイプラインステージ
作業項目 ID（複数可）またはソースステージ ID — プロモーションの対象に応じて指定します。sf devops promote では --work-item-id（繰り返し指定可能）と --stage-id のどちらか一方を指定します
統合プロモーションの場合：メタデータを共有する親作業項目 ID と、1つ以上の子作業項目 ID
ターゲット組織：--target-org <alias>（target-org 設定変数が設定されていない場合は必須）

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

出力形式：ヘッドレスでの利用には --json
テストレベル：開発ステージへのデプロイでは --test-level を省略します（デフォルトは NoTestRun）。Apex を含む本番ステージへのデプロイでは RunLocalTests を使用します

ユーザーの依頼が明確な場合（「作業項目 1fkxx… をステージ 1QVxx… にプロモートして」「QA ステージを UAT にプロモートして」「これらの作業項目を統合してプロモートして」など）は、必要な ID が揃い次第、処理を進めてください。

ワークフロー

すべての操作では、--json 出力を指定した sf devops CLI コマンドを使用します。必ず最初に validate を実行してください。すべてのプロモーションコマンドでは、作業項目名ではなくレコード IDを指定します。必要に応じて、先に名前を ID に解決してください。

フェーズ 1 — 認証と検証

操作の前に、組織の認証を確認します。
```
sf org display --json
```
- 失敗した場合は、sf org login web --set-default --alias <alias> を実行するようユーザーに案内してください
- 以降のすべてのコマンドに --target-org <alias> を指定してください（target-org 設定変数が設定されていない場合は必須）
必須の validate ステップを実行します — これは必須であり、prepare／combine／promote の前に必ず実行します。sf devops promotion validate では、ターゲットステージ（-t/--target-stage-id）と、1つ以上の -i/--work-item-id が必要です。
```
# Capture the output — Phase 2 derives the combine decision from it deterministically.
VALIDATE_JSON=$(sf devops promotion validate --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json)
```
- 作業項目をターゲットステージにプロモートできるか検証します。プロモーションを試みる前に、VCS とオブジェクト権限のエラー（関連付けられた PR が必要であることも含む）を確認します
- 1回の呼び出しで複数の作業項目を検証するには、--work-item-id を繰り返し指定します
- 成功：status == 0 かつ .result.success == true の場合は、次に進みます
- 検証に失敗した場合（ゼロ以外の終了コード。例：.result.errorType／.result.errorDetails が設定された VCS_ERROR: No pull request exists…）：処理を停止します。エラーを報告し、先に進まないでください。メタデータの重複に関するエラーの場合は、再試行する前に競合を解決してください
- 共有コンポーネント：.result.combineDetails が null でない場合、作業項目はメタデータを共有しています。validate は親／子のグループ分けと suggestions を返します。これはフェーズ 2 で統合するかどうかを判断するための信頼できる情報です（手順 4 を参照）。統合するかどうかを推測しないでください。フェーズ 2 のスクリプトは VALIDATE_JSON から .result.combineDetails を読み取ります

フェーズ 2 — 準備（必要に応じて結合）

昇格に向けて作業項目を準備します。
```
sf devops work-item prepare --work-item-id <id> --target-stage-id <target-stage-id> --target-org <alias> --json
```
- --target-stage-id は必須です。作業項目の昇格先と同じステージを指定します
- 冪等性があります。準備済みの作業項目を再実行しても安全なので、成功として扱ってください
作業項目を結合します — フェーズ 1 の検証ステップで共有コンポーネントが報告された場合（.result.combineDetails が null ではない場合）、または作業項目に依存関係があり、1 つの単位として昇格する必要がある場合に限ります。JSON を目視で判断しないでください。保存した検証結果（VALIDATE_JSON）から、結合の要否と親／子の ID を決定論的に導き出してください。
```
# COMBINE == "true" only when validate returned a combineDetails block.
COMBINE=$(printf '%s' "$VALIDATE_JSON" | jq -r '(.result.combineDetails != null)')
if [ "$COMBINE" = "true" ]; then
  PARENT_ID=$(printf '%s' "$VALIDATE_JSON" | jq -r '.result.combineDetails.parentWorkitemId')
  # one --child-work-item-id arg per child, safe for use as a flag array
  CHILD_ARGS=()
  while IFS= read -r cid; do CHILD_ARGS+=(--child-work-item-id "$cid"); done < <(
    printf '%s' "$VALIDATE_JSON" | jq -r '.result.combineDetails.childWorkitemsId[]')
fi
```
導き出した値を使って結合します（COMBINE が "true" でない場合は、このコマンドを完全に省略してください）。
```
sf devops work-item combine \
  --parent-work-item-id "$PARENT_ID" \
  "${CHILD_ARGS[@]}" \
  --target-stage-id <stage-id> \
  --target-org <alias> \
  --json
```
- CHILD_ARGS は、子作業項目ごとに --child-work-item-id <id> のペア 1 つに展開されます
- 親作業項目はパイプラインを続行する主項目です。昇格時に子の変更は親のブランチにマージされます
- 結合後は、ステップ 5 で親作業項目 ID を昇格します

フェーズ 3 — 昇格

対象ステージに昇格します — --work-item-id または --stage-id のどちらか一方のみを指定する必要があります。--target-stage-id は常に必須です。--skip-validation を指定するのは、現在のセッションで昇格対象のすべての作業項目についてフェーズ 1 の検証ステップが正常に完了した場合に限ります。それ以外の場合は、このフラグを省略し、CLI に組み込みの検証を実行させてください。
- 特定の作業項目を 1 つ以上昇格します（作業項目ごとに --work-item-id を繰り返します。結合して昇格する場合は親の ID を使用してください）。フェーズ 1 の検証がこのセッションで成功した場合に限り、--skip-validation の行を含めます。それ以外の場合は、その行を削除してください。
```
sf devops promote \
  --work-item-id <id> \
  --target-stage-id <target-stage-id> \
  --skip-validation \
  --target-org <alias> \
  --json
```
- または、ソースステージから承認済みの作業項目をすべて昇格します（この場合も、フェーズ 1 の検証がこのセッションで成功した場合に限り、--skip-validation の行を含めます）。
```
sf devops promote \
  --stage-id <source-stage-id> \
  --target-stage-id <target-stage-id> \
  --skip-validation \
  --target-org <alias> \
  --json
```
- 条件付きである理由： sf devops promote の組み込みの昇格前検証では、フェーズ 1 の sf devops promotion validate ステップと同じチェックが実行されます（関連付けられた PR の要件を含みます）。このセッションでワークフロー全体を順に実行した場合、検証はすでに成功しているため、--skip-validation は重複した再実行を省くだけです。しかし、エージェントがワークフローの途中から再開した場合、フェーズ 1 の検証を行わずに昇格を実行する場合、または昇格対象のすべての作業項目についてフェーズ 1 を実行していない場合は、--skip-validation を指定しないでください。その場合にこのフラグを指定すると、事前の安全確認なしに検証が完全に省略されます
- 対象ステージにまだない変更だけでなく、ブランチ内のすべてのメタデータをデプロイするには、--deploy-all を追加します
- Apex を含む本番ステージへのデプロイでは、--test-level RunLocalTests（または RunSpecifiedTests --tests <names>）を追加します
- デプロイは非同期で実行されます。JSON の .result から、返された昇格／デプロイ ID を取得します

フェーズ 4 — 完了と報告

昇格を完了して確定します。対象ステージ内の作業項目が次に進みます。
```
sf devops promotion complete --target-stage-id <target-stage-id> --target-org <alias> --json
```
- 昇格デプロイが成功した後に実行し、対象ステージで昇格を完了としてマークします
- --target-stage-id は必須です（作業項目の昇格先と同じ対象ステージを指定します）
結果を報告します。
- 各ステップで CLI がステータス 0 を返したことを確認します
- 昇格／デプロイ ID を報告し、非同期デプロイの完了は別途追跡することを伝えます
- このスキル内で処理をブロックしたり、完了まで待ち続けたりしないでください。ID を提示して終了します
- 昇格について明確に伝えます。例：「作業項目の昇格を開始しました（ソースステージ → 対象ステージ）。デプロイ ID：。この ID をポーリングしてデプロイの完了を確認し、その後に promotion complete を実行してください。」

ルール／制約

制約	理由
Validate は必ず最初に実行します	変更を加える前に前提条件が満たされていることを保証します。スキップすると、パイプラインの状態が破損する可能性があります
すべての `sf devops` コマンドで `--json` を使用します	ヘッドレスで処理するには構造化出力が必要です。人間向けの出力は解析の信頼性に欠けます
コマンドでは名前ではなくレコード ID を指定します	`--work-item-id`、`--stage-id`、`--target-stage-id`、`--parent/--child-work-item-id` にはすべて ID を指定します。最初に名前を ID に解決してください
すべての昇格コマンド（validate、prepare、combine、promote、complete）で `--target-stage-id` が必須です	ターゲットステージは必須です。指定しないと、昇格先がありません
promote では `--work-item-id` または `--stage-id` のどちらか一方だけを指定します	これらのフラグは相互排他的です。特定の項目、またはソースステージ全体のどちらかを昇格します
`--skip-validation` を promote に指定するのは、このセッションで Phase 1 の validate が成功した場合に限ります	CLI に組み込まれた promote 前の検証では、Phase 1 の `promotion validate` ステップと同じチェック（関連する PR の必須要件を含む）が実行されます。このセッションですでに検証が正常に完了している場合に限り、安全にスキップできます。エージェントがワークフローの途中から再開した場合、または先行する validate なしで昇格が実行された場合は、CLI に検証させるため、このフラグを省略してください
Deploy は非同期で実行されます。識別子を取得して報告してください	promote の deploy は同期的には完了しません。完了状況は別途追跡されます
このスキルでは deploy の完了をビジーウェイトしないでください	ポーリングは別の処理です。ここで待機するとターンを無駄にし、タイムアウトのリスクも高まります
Combine は作業項目でメタデータや依存関係が共有されている場合に限って使用します	Combine は競合しやすい項目や依存関係のある項目に使用するものであり、複数項目を昇格するたびに使うものではありません
Prepare はべき等です	CI で安全に再試行できます。完了済みの prepare を再実行しても何も起こりません
対話型プロンプトは使用しないでください	スキルはヘッドレスで実行されます。すべての入力を CLI フラグで指定する必要があります
ID は CLI フラグとして渡し、シェル文字列に埋め込まないでください	細工された識別子によるプロンプトインジェクションやコマンドインジェクションを防ぎます

注意点

問題	対処
検証に失敗した場合	STOP — prepare、combine、promote を実行しないでください。ゼロ以外のステータス／エラーメッセージを報告してください。メタデータの重複が原因の場合は、再試行する前に競合を解決してください
デフォルトの組織が設定されていない場合	`sf org display --json` を実行してください。失敗した場合は、`sf org login web --set-default` を実行するようユーザーに案内してください
ID の代わりに作業項目名を渡した場合	昇格コマンドにはレコード ID が必要です。次のコマンドで名前を ID に解決してください：`sf devops work-item list --project-id <id> --json \| jq -r '.result.workItems[] \| select(.subject == "<WI-subject>") \| .id'`
`--work-item-id` と `--stage-id` の両方を指定した場合	これらは相互排他的です。特定の作業項目かソースステージのどちらか一方を選び、両方は指定しないでください
`--target-stage-id` が指定されていない場合	すべての昇格コマンド（validate、prepare、combine、promote、complete）で必須です。パイプライン構成からターゲットステージ ID を取得してください
Combine による昇格で、誤った項目が昇格される場合	`work-item combine` の後は、親作業項目の ID を使って昇格してください。子項目は親のブランチにマージされます
Deploy が同期的に完了すると見なしている場合	promote の deploy は非同期です。識別子を取得し、完了を確認してから `promotion complete` を実行してください
Apex カバレッジが原因で本番 deploy に失敗した場合	Apex を含む本番ステージへの昇格では、`--test-level RunLocalTests`（または `RunSpecifiedTests --tests <names>`）を設定してください
競合により deploy に失敗した場合	検証をすり抜けて競合が発生しました。メタデータの競合を解決してから、再検証して再試行してください

出力の想定

操作によって成果物が異なります。

Validate：.result.success。作業項目がメタデータを共有している場合は、.result.combineDetails／.result.suggestions も含まれます。終了コードが 0 以外の場合（.result.errorType／.result.errorDetails が含まれます）、その作業項目を対象ステージに昇格できません
Prepare / combine：作業項目がステージングされたことの確認（combine では親／子のグループ分けが返されます）
Promote：非同期デプロイ識別子と、昇格デプロイが開始されたことの確認
Promotion complete：作業項目が対象ステージに進んだことの確認

出力は、sf devops work-item、sf devops promote、sf devops promotion complete CLI コマンドから取得されます。非同期デプロイの完了は promote 呼び出しでは返されません。完了処理の前に、返された識別子を別途ポーリングしてください。

スキル間の連携

タイミング	アクション
作業項目を作成するか、まず昇格可能なステータスに移動する必要がある場合	`dx-devops-work-item-manage` に委任します
検証でメタデータの重複／競合が報告された場合	再試行する前にメタデータの競合を解決します
完了を確認するために promote デプロイ識別子をポーリングする必要がある場合	返された識別子を別途ポーリングしてから、`sf devops promotion complete` を実行します

参照ファイル一覧

ファイル	読み込むタイミング
`references/cli-commands.md`	validate／prepare／combine／promote／complete の詳細な CLI フラグの説明、JSON 出力スキーマ、エラー処理パターンが必要な場合
`examples/promotion-workflows.md`	ユーザーのリクエストが一般的なパターン（単一の作業項目の昇格、昇格の統合、ステージ全体の昇格、検証を先に行うゲート）に該当する場合

Markdown 対応

ログインしてコメント

基本情報

作者: forcedotcom
リポジトリ: forcedotcom/sf-skills
カテゴリ: クラウド・DevOps
インストール数: 2,301
GitHub スター: 1,127

問題を報告