dx-devops-conflict-resolve

DevOps Center の競合とデプロイ失敗の解決

作業項目のフィーチャーブランチを DevOps Center で昇格するときに妨げとなる問題を診断し、解決します。DevOps Center は Git を基盤としており、各作業項目はフィーチャーブランチ、各パイプラインステージはターゲットブランチです。昇格が失敗する原因は 2 つあります。Git のマージ競合（複数の作業項目が同じメタデータを変更した場合）と、デプロイ失敗（デプロイ自体でエラーが発生した場合。多くは依存関係の不足）です。sf devops conflict CLI コマンドはありません。どちらの場合も、接続されたリポジトリに対して標準の git を使って診断し、解決します。このスキルは、そのリポジトリのローカルクローンで実行します。

対象範囲

• 対象：（a）作業項目のフィーチャーブランチとターゲットステージブランチ間のマージ競合を（破壊的な変更を加えずに）検出し、競合ファイルを解決（どちらかの側を選択するか、競合マーカーを手動でマージ）して、DevOps Center が追跡するフィーチャーブランチにコミットおよびプッシュします。（b）昇格のデプロイ失敗を診断し、マージ競合かデプロイエラーかを分類し、不足している依存関係を解析して、完全昇格で解決できるか（コンポーネントがフィーチャーブランチに存在するか）、それとも先にコンポーネントを追加する必要があるかを判断します
• 対象外：昇格、完全昇格、または結合の実行（dx-devops-promote を使用）、作業項目またはそのステータスの作成・更新（dx-devops-work-item-manage を使用）、組織へのメタデータの直接デプロイ、パイプラインまたはプロジェクトの設定（別のスキルを使用）

---

必要な入力

作業を始める前に、次の情報を収集するか推定してください。

• DevOps Center に接続された Git リポジトリのローカルクローン（エージェントはここで git コマンドを実行します）。開始前に作業ツリーがクリーンであることを確認してください。
• フィーチャーブランチ名 — 作業項目に対応するブランチです。ユーザーが代わりに作業項目 ID／件名を指定した場合は、そのブランチを特定します（sf devops work-item による検索方法は Reference File Index を参照してください）。
• ターゲットステージブランチ名 — 作業項目の昇格先となるパイプラインステージのブランチです（例：integration／UAT ブランチ）。
• リモート名 — 既定値は origin です。
• デプロイエラーテキスト（デプロイ失敗のトラックのみ）— 昇格時のエラー出力／概要です。失敗の分類と不足している依存関係の解析に必要です。診断スクリプトに渡せるよう、ファイルに保存するか、パイプで入力してください。

特に指定がない場合の既定値：

• リモート：origin
• マージ方向：ターゲットステージブランチをフィーチャーブランチにマージします（作業項目を昇格先の状態に合わせます）

ユーザーが両方のブランチ（「uat に対する feature/WI-101 の競合を解決して」）を指定した場合は、そのまま進めます。作業項目を指定した場合は、先にそのブランチを特定します。

---

ワークフロー

DevOps Center の昇格を妨げる問題は、Git レベルのものです。検出と診断はスクリプトで確実に行えます。競合ファイルごとの解決には判断が必要です。検出前に解決しようとしてはいけません。また、作業ツリーがクリーンであることを先に確認してください。

最初にトラックを選択します。 ユーザーの状況に基づいて、次のいずれかを選びます。

• マージ競合トラック — ユーザーが昇格前の競合チェックを求めている場合、または昇格が失敗し、原因がマージ競合である、あるいはその疑いがある場合 → 以下のフェーズ 1～4
• デプロイ失敗トラック — 昇格時にデプロイがエラーメッセージを伴って失敗し、ユーザーが原因と解決方法を知りたい場合 → フェーズ D。フェーズ D で失敗がマージ競合と分類された場合は、マージ競合トラックに進みます。

フェーズ 1 — 認証と状況確認

1. ローカルリポジトリとクリーンな作業ツリーを確認します。 リポジトリのクローン内で実行します。

   git rev-parse --is-inside-work-tree && git status --porcelain
   

   • git status --porcelain が何かを出力する場合、作業ツリーは汚れています。最初にコミットするか stash するようユーザーに指示してください。汚れた作業ツリーで試行マージを行うのは安全ではありません。
2. 作業項目をブランチに対応付けます（ユーザーがブランチではなく作業項目を指定した場合のみ）。 sf org display --json を実行して組織の認証を確認します。失敗した場合は、sf org login web --set-default --alias <alias> を実行するようユーザーに伝えてください。その後、ブランチを検索します。詳しくは references/git-conflict-resolution.md を参照してください。

フェーズ 2 — 検出（非破壊）

3. **検出スクリプトを実行します。**スクリプトは対象ブランチを取得し、コミットせずにフィーチャーブランチへ試験的にマージして、競合しているファイルを一覧表示した後、試行を中止するため、作業ツリーは変更されません。

   scripts/detect-conflicts.sh <feature-branch> <target-branch> [remote]
   

   • 終了コード 0 = マージがクリーン（競合なし）→「昇格しても安全」と報告して終了します。
   • 終了コード 2 = 競合あり → スクリプトが競合ファイルの一覧を表示します。フェーズ 3 に進みます。
   • 終了コード 1 = エラー（汚れた作業ツリー、不明なブランチ、フェッチ失敗）→ エラーを報告して終了します。エラーを「競合なし」として扱わないでください。

フェーズ 3 — 解決

4. 実際のマージを開始し、作業ツリーに競合マーカーを反映します。

   git checkout <feature-branch>
   git merge --no-ff <remote>/<target-branch>
   

   競合ファイルを決定的な順序で一覧表示します。

   git diff --name-only --diff-filter=U
   

5. 競合している各ファイルを解決します — ここで判断が必要です。
   • どちらか一方が明らかに正しい場合は、その側を採用します。git checkout --ours -- <file>（フィーチャーブランチのバージョンを保持）または git checkout --theirs -- <file>（対象ブランチのバージョンを採用）を実行します。DevOps Center では、「ours」はフィーチャーブランチ、「theirs」は対象ステージブランチです。
   • 両方に必要な変更が含まれている場合（同じコンポーネントに対する相違する編集）は、ファイルを開いて手動でマージします。<<<<<<< / ======= / >>>>>>> の領域を調整して、両方の意図を保った正しいバージョンにします。XML メタデータ（.xml、.object-meta.xml、.field-meta.xml）では特に注意し、ファイルの整形式を保ち、要素を重複させないでください。
   • 解決した各ファイルをステージします：git add <file>。
6. コミットする前に、マーカーが残っていないことを確認します。

   git diff --check
   git diff --name-only --diff-filter=U
   

   • git diff --check が何も報告せず、未マージファイルの一覧が空である必要があります。どちらかに残りがある場合は、解決を続けてください。コミットしてはいけません。

フェーズ 4 — 仕上げと報告

7. DevOps Center が取り込めるよう、追跡対象のフィーチャーブランチに解決内容をコミットしてプッシュします。

   git commit --no-edit          # completes the merge with the default merge message
   git push <remote> <feature-branch>
   

8. 結果を報告します。
   • 競合なし：「<feature> と <target> の間にマージ競合はありません。昇格しても安全です。」
   • 解決済み：解決したファイルと解決方法（片方を採用したか、手動でマージしたか）を一覧表示し、フィーチャーブランチをプッシュしたことを伝えます。その後、次の手順に引き継ぎます：「dx-devops-promote を使用して再検証し、昇格してください。」

Phase D — デプロイ失敗の診断

プロモーションの deploy がエラーで失敗し、ユーザーが原因と解決方法を知りたい場合は、このトラックを使用します。診断はスクリプトで決定的に行います。エラーを目視で判断しないでください。

D1. デプロイエラーのテキストをファイルに保存するか、診断スクリプトに直接パイプします。

D2. リポジトリのクローンから診断スクリプトを実行します。失敗を分類し、不足している依存関係を解析し、そのコンポーネントがフィーチャーブランチに存在するかどうかを確認します（git show を使用）：

scripts/diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]
# or:  <deploy command> 2>&1 | scripts/diagnose-deploy-failure.sh - <feature-branch> <target-branch>

終了コードと出力された REASON／RECOMMENDATION に従って対応します：

• 終了コード 0（dependency_in_feature_branch）→ 不足しているコンポーネントはフィーチャーブランチに存在しますが、デプロイ対象から漏れています。フルプロモーションで解決できるはずです。このことを報告してユーザーに確認し、フルプロモーションを実行するために dx-devops-promote に引き継ぎます。このスキルではプロモーションを実行しません。
• 終了コード 2（merge_conflict）→ 失敗の原因はデプロイエラーではなく、マージコンフリクトです。マージコンフリクトのトラック（Phase 1 以降）に進みます。
• 終了コード 3（dependency_not_in_feature_branch）→ 不足しているコンポーネントはフィーチャーブランチに存在しないため、プロモーションでは補えません。プロモーション前に、そのコンポーネントをフィーチャーブランチに追加してコミットするか、所有する作業項目を含める必要があることを報告します。
• 終了コード 4（no_dependency_parsed）→ 認識可能な依存関係の不足エラーではありません。生のエラーを報告し、根本原因（テストカバレッジや無効なメタデータなど）の修正を提案します。フルプロモーションでは解決しません。
• 終了コード 1 → 環境／使用方法のエラー（git リポジトリではない、エラーファイルを読み取れないなど）です。報告して停止します。

D3. 診断結果を報告します。REASON、フルプロモーションで解決できるかどうか、不足しているコンポーネント（あれば）とその場所、具体的な次の手順を伝えます。むやみに再プロモーションしないでください。dependency_in_feature_branch と診断された場合に限り、フルプロモーションを提案します。

---

ルール／制約

制約	理由
作業ツリーがダーティな状態で、試験的なマージやマージを行わない	未コミットの変更がある状態で進行中のマージを行うと、ユーザーの作業を取り返しのつかない形で損なう可能性があります
解決（Phase 3）より先に、必ず検出（Phase 2）を行う	検出は非破壊的です。コンフリクトの範囲を把握せずに実際のマージに進むと、混乱した中途半端なマージになる危険があります
目視ではなくスクリプトでコンフリクトを検出する	scripts/detect-conflicts.sh は決定的で再現可能なコンフリクト一覧を生成し、試験的なマージ後には必ずクリーンアップします
検出時のゼロ以外のエラーを「コンフリクトなし」とみなさない	終了コード 0（クリーン）の場合にのみ安全にプロモーションできます。終了コード 1 はチェック失敗を意味するため、報告する必要があります
ターゲットのステージブランチをフィーチャーブランチにマージする	作業項目を宛先と整合させます。DevOps Center はフィーチャーブランチをプロモーションするため、解決結果はそのブランチに存在する必要があります
コミット前にコンフリクトマーカーが残っていないことを確認する（git diff --check）	未解決のマーカーを含む状態でコミットすると、メタデータとプロモーションが破損します
メタデータを手動でマージする際は、XML の整形式性を保つ	不正な形式の -meta.xml はデプロイを妨げます。要素の重複や途中で切れた要素を残さないでください
作業項目のフィーチャーブランチのみをプッシュする	解決結果は作業項目のブランチに属します。ステージ／統合ブランチに直接プッシュしないでください
このスキルではプロモーションやデプロイを行わない	解決は、コンフリクトのない状態でプッシュしたブランチ、または診断結果をもって終了します。フルプロモーションを含むプロモーションは dx-devops-promote が担当します
目視ではなくスクリプトでデプロイ失敗を診断する	scripts/diagnose-deploy-failure.sh は失敗を決定的に分類し、git show でブランチ上の存在を検証します
不足しているコンポーネントがフィーチャーブランチにある場合に限り、フルプロモーションを提案する	コンポーネントが存在しなければ、ブランチをプロモーションしても補えません。再プロモーションしても再び失敗するだけです

---

注意点

問題	解決策
sf devops conflict CLI コマンドは存在しません	DevOps Center の競合は Git の競合です。sf devops のサブコマンドではなく、git で解決してください。このスキルは設計上、git ベースです
作業ツリーに未コミットの変更がある	git status --porcelain が空である必要があります。検出や解決の前に、コミットまたは stash するようユーザーに案内してください
ユーザーがブランチではなく作業項目を指定した	まず sf devops work-item で作業項目を対応するフィーチャーブランチに解決してください。references/git-conflict-resolution.md を参照してください
スクリプトのゼロ以外の終了コードをクリーンと判定する	終了コード 2 = 競合、終了コード 1 = エラーです。「昇格しても安全」なのは終了コード 0 の場合だけです
マーカーが残ったままコミットする	git diff --check を実行し、git commit の前に --diff-filter=U の一覧が空であることを確認してください。<<<<<<<／>>>>>>> マーカーが残っているとメタデータが破損します
--ours／--theirs が逆になっている	ターゲットをフィーチャーブランチにマージする場合、--ours = フィーチャーブランチ、--theirs = ターゲットのステージブランチです
手動マージした XML の形式が不正	-meta.xml の整形式を維持し、要素を重複させないでください。ステージングする前に、ファイルを再度パースして確認してください
detached HEAD／古いブランチ	まず git fetch を実行してください。マージする前に、フィーチャーブランチを追跡ブランチとしてチェックアウトしてください（スクリプトが代わりに fetch を実行します）
昇格後に競合が再発し、処理も失敗する	ターゲットブランチが更新されています。現在のターゲットブランチに対して検出を再実行し、再度解決してください
原因を調べずにデプロイ失敗を再昇格する	まず scripts/diagnose-deploy-failure.sh を実行してください。終了コード 0 = コンポーネントはブランチ上にあり、全体の昇格で修正できます。終了コード 2 = マージ競合です（トラックを切り替えてください）。終了コード 3 = コンポーネントが存在しません。昇格する前に追加してコミットするか、所有する作業項目を含めてください。昇格だけでは補えません

---

出力の想定

このスキルが生成するのは、競合のないフィーチャーブランチまたはデプロイ失敗の診断であり、組織の変更ではありません。

• 競合なし：フィーチャーブランチがターゲットのステージブランチに問題なくマージされることの確認。昇格しても安全です
• 競合を解決済み：作業項目のフィーチャーブランチ上で、ターゲットのステージブランチとの整合性を取ったマージコミットを作成してリモートにプッシュし、解決したファイルと解決方法（片方を採用したか、手動でマージしたか）を報告します
• デプロイ失敗の診断：失敗の理由（マージ競合／ブランチ内の依存関係不足／ブランチ外の依存関係不足／不明）と、全体の昇格で修正できるかどうか、不足しているコンポーネントとその格納場所、具体的な次の手順を示すレポートです

メタデータはデプロイされず、組織の状態も変更されません。成果物は、プッシュ済みで競合のないブランチ、または診断と推奨される次の手順です。

---

スキル間の連携

条件	アクション
ブランチに競合がない（または競合を解決してプッシュ済み）ため、次に進む準備ができている	dx-devops-promote に委任して、検証と昇格を行います
作業項目名／ID を対応するフィーチャーブランチに解決する必要がある、または候補の作業項目を一覧表示する必要がある	dx-devops-work-item-manage を使用します
作業項目間でメタデータを共有しており、個別に解決する代わりにまとめて昇格できる	手動マージではなく、dx-devops-promote の結合ステップを使うことを検討してください
昇格時のデプロイがすでに競合で失敗している	現在のターゲットブランチに対して再検出し、解決してプッシュした後、dx-devops-promote で再昇格します
診断結果が、全体の昇格で失敗を修正できることを示している（dependency_in_feature_branch）	全体の昇格を実行するために dx-devops-promote に引き継ぎます。このスキルでは昇格を行いません
昇格の前に、不足しているコンポーネントをフィーチャーブランチに追加する必要がある	コンポーネントを作成してコミットするか、所有する作業項目を含めます。メタデータの生成には該当するドメインスキルを使用し、その後 dx-devops-promote で再昇格します

---

参照ファイル一覧

ファイル	読むタイミング
scripts/detect-conflicts.sh	フェーズ 2 — 機能ブランチと対象ステージブランチ間のマージコンフリクトを非破壊で検出するために実行します
scripts/diagnose-deploy-failure.sh	フェーズ D — 昇格デプロイの失敗を分類し、完全な昇格（または依存関係の不足を修正すること）で解決できるか判断するために実行します
references/git-conflict-resolution.md	Git コマンドの完全なリファレンス、sf devops work-item からブランチを検索する方法、または --ours／--theirs と XML マージのガイダンスが必要な場合
references/deploy-failure-resolution.md	フェーズ D — デプロイ失敗の判断ツリー、エラー解析パターン、または診断スクリプトの根拠となる完全な昇格についての説明が必要な場合
examples/conflict-workflows.md	ユーザーの依頼が一般的なパターン（昇格前のコンフリクト確認、一方を選択する解決方法、XML の手動マージ、昇格失敗のトラブルシューティング、デプロイ失敗の診断）に当てはまる場合