dx-devops-work-item-manage

DevOps Center 作業項目の管理

DevOps Center での作業項目のライフサイクル全体を管理します。作成からステータスの変更、プロモーションの準備完了までを対象とします。自律的なリリースワークフロー向けに、ヘッドレスな CLI 駆動の操作を提供します。

対象範囲

• 対象範囲内: 作業項目の一覧表示、新しい作業項目の作成、作業項目のブランチへの変更のコミット、作業項目のフィールド（件名、説明、ステータス）の更新、作業項目のステータスの変更（New → In Progress → Ready to Promote）、作業項目のブランチのプルリクエストの作成
• 対象範囲外: プロモーション／デプロイ、競合の検出、パイプラインまたはプロジェクトの管理（別のスキル）

---

必須入力

続行する前に、以下の情報を収集するか推定してください。

• 操作の種類: list、create、update、commit、create-review
• list の場合: プロジェクト ID（必須）。指定されていない場合は sf devops project list --json で取得します
• create の場合: プロジェクト ID（必須）、件名（必須）、説明（任意）
• commit の場合: 作業項目名または ID（必須）、コミットメッセージ、およびコミットするファイル（git パス）またはコンポーネント（API パス）。任意項目: dev org エイリアス — 変更が含まれる組織です。指定されている場合は、まず DevOps Center の commit API を試してください（手順 5 を参照）。それ以外の場合は git を使用します
• update の場合: 作業項目名（例: WI-000001）または作業項目 ID（必須）、更新するフィールド（件名、説明、ステータス）
• create-review の場合: 作業項目名（例: WI-000001）または作業項目 ID（必須）

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

• 出力形式: ヘッドレスでの利用向けに --json
• 作業項目の識別子: 両方を利用できる場合は、--work-item-id より --work-item-name（WI-000001）を優先します（名前のほうが人間にとって読みやすいため）

ユーザーが明確な依頼（「Project Alpha の作業項目を一覧表示」「ログインのバグを修正する作業項目を作成」「WI-12345 を In Progress に移動」「WI-12345 の PR を作成」など）をした場合は、不要な質問をせずにすぐに進めてください。

---

ワークフロー

操作には sf devops work-item CLI コマンドを --json 出力付きで使用します。API コミットパスでも sf api request rest と sf data query を使用します。

フェーズ 1 — 操作の特定

1. ユーザーの意図から操作の種類を判断します。
   • 「list」「show」「find」などのキーワード → list 操作
   • 「create」「new」「add」などのキーワード → create 操作
   • 「commit」「push」「save changes」「git commit」などのキーワード → commit 操作
   • 「update」「change」「modify」「edit」「move」「transition」「advance」「mark as」などのキーワード → update 操作
   • 「create PR」「pull request」「code review」「review」「open PR」などのキーワード → create-review 操作

フェーズ 2 — 操作の実行

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

   sf org display --json
   

   • デフォルト組織が設定されていない場合、または認証の有効期限が切れている場合は、次のコマンドを実行するようユーザーに案内してください。

     sf org login web --set-default --alias <alias>
     

   • プロジェクトの一覧表示を試みて、認証済みの組織で DevOps Center が有効になっていることを確認します
   • ユーザーが特定の組織を対象にしたい場合は、以降のすべてのコマンドで --target-org <alias> を使用します
   • API コミットパスでは、dev org と hub org の両方に対して sf org display --target-org <alias> --json を実行します

3. 作業項目を一覧表示する — ユーザーが既存の作業項目を確認したい場合：

   sf devops work-item list --project-id <project-id> --json
   

   • --project-id は必須です。ユーザーが ID ではなくプロジェクト名を指定した場合は、まず sf devops project list --json を実行して、名前から ID を特定します。
   • コマンドがステータス 0（成功）を返すことを確認します。
   • JSON 出力を解析します。作業項目は .result[] 配列にあります。
   • 各作業項目には、name（例：WI-000001）、subject、branch、environment、status、description があります。
   • 作業項目名、件名、ステータス、ブランチ、環境がわかる、読みやすい形式で提示します。
   • .result[] が空の配列の場合は、「プロジェクト に作業項目はありません。」と確認します。
   • ユーザーがステータスによる絞り込み（例：「Ready to Promote ステータスの作業項目を表示」）を求めた場合は、次を実行します。

     sf devops work-item list --project-id <id> --json | jq '.result[] | select(.status == "<requested-status>")'
     

     その後、一致した作業項目を提示します。

4. 作業項目を作成する — ユーザーが新しい作業項目の作成を求めた場合：

   sf devops work-item create \
     --project-id <project-id> \
     --subject "<subject>" \
     --description "<description>" \
     --json
   

   • --project-id は必須です（ユーザーから取得するか、sf devops project list --json で取得します）。
   • --subject は必須です（ユーザーに表示するタイトル）。
   • --description は任意です（省略した場合は空欄になります）。
   • JSON 出力から、返された作業項目名（例：WI-000001）、ブランチ名、環境を取得して、後続の操作に備えます。
   • 冪等性があります。ユーザーが重複（同じ件名＋プロジェクト）の作成を試みた場合は、まず一覧で確認し、既存の作業項目を返します。

5. コミット操作を実行する — 操作の種類が commit の場合。まず実行経路を選択します。

   • API 経路 — ユーザーが開発組織のエイリアスを指定し、かつ変更がすでにその開発組織にデプロイされている場合に限ります（不明な場合は、sf project deploy start でデプロイするか、git を使うか確認します）。開発組織のエイリアス：commitChanges、DevopsRequestInfo。ハブのエイリアス：sf devops、WorkItemComponentList。DevOps Center は、開発組織から指定されたコンポーネントを取得し、DevOps Center <[email protected]> としてコミットします。
   • Git 経路 — 上記以外の場合。変更が開発組織にのみ存在する場合は、まず sf project retrieve start --target-org <dev-org> を実行します。

   API 経路（コマンド、リクエスト本文、エラーコード、ポーリングについては references/commit-api.md を参照）：

   1. 開発組織で GET /connect/devops/doceConnectionType を事前確認します。呼び出しの失敗（終了コードが 0 以外、またはエラーボディ）や、isCore が true でない場合は、Git 経路を使用します。
   2. sf devops project list → プロジェクト ID を取得し、次に sf devops work-item list --project-id <id> --target-org <hub> → 作業項目 ID と名前を取得します。ステータスは New、In Progress、In Review、Ready to Promote のいずれかである必要があります。
   3. 開発組織で POST /connect/devops/commitChanges を実行します。リクエスト本文には内部オブジェクトを指定します（commitChanges ラッパーは付けません）。
   4. 呼び出しに失敗した場合、または reqId が CODE:message 形式の status: "ERROR" が返された場合は、その内容を伝えて処理を停止します。
   5. POST の status が SUCCESS の場合（受け付けられたことのみを示します）、開発組織で DevopsRequestInfo WHERE RequestToken = '<reqId>' を 10 秒ごとにポーリングし、Status が SUCCESS または ERROR になるまで続けます（Message／ErrorDetails を報告します）。期限は 12 分です。期限を過ぎた場合、リクエストは停止しているため、その旨を報告し、自動で再試行しないでください。
   6. レビューを作成する前に、ハブに新しい WorkItemComponentList が存在することを確認します。

   Git 経路：

   • 作業項目が New の場合は、まず In Progress に設定します（手順 6）。ハブは New の間に行われたプッシュを無視します。
   • 作業項目の branch フィールドをブランチとして使用します。
   • 標準的な git ワークフロー：

     git checkout <branch-name>
     git add <files>
     git commit -m "<commit-message>"
     git push origin <branch-name>
     

   • ハブはプッシュを非同期で登録します。PR を作成する前に、登録を再確認してください。

6. 作業項目を更新する — ユーザーが件名、説明、またはステータスの変更を希望する場合：

   sf devops work-item update \
     --work-item-name <WI-name> \
     --subject "<new-subject>" \
     --description "<new-description>" \
     --status "<In Progress|Ready to Promote>" \
     --json
   

   • 作業項目の識別子が必要です。--work-item-name <WI-000001>（推奨）または --work-item-id <id> を使用します
   • ユーザーが名前ではなく件名で作業項目を指定した場合は、まず名前に解決します：

     sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<user-provided-subject>") | .name'
     

     次に、返された名前（例：WI-000001）を更新コマンドに渡します
   • --subject、--description、--status のいずれかを必ず指定します
   • 有効なステータス値は「In Progress」または「Ready to Promote」です（スペースを含む正確な文字列）
   • 更新するフィールドのフラグのみを指定します（変更しないフィールドは省略します）
   • コマンドがステータス 0（成功）を返すことを確認します
   • JSON 応答を解析します。.result.name、.result.subject、.result.status に更新後の値が含まれます
   • ステータス遷移の場合：コマンドの完了後、応答の .result.status を確認して、新しいステータスを明示的に確認します。更新応答にステータスフィールドがない場合は、一覧から作業項目を再取得し、ステータスが反映されていることを確認します

7. プルリクエストを作成する — ユーザーがコードレビュー用の PR 作成を希望する場合：

   sf devops review create \
     --work-item-name <WI-name> \
     --json
   

   • 作業項目の識別子が必要です。--work-item-name <WI-000001>（推奨）または --work-item-id <id> を使用します
   • ユーザーが名前ではなく件名で作業項目を指定した場合は、まず名前に解決します：

     sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<user-provided-subject>") | .name'
     

     次に、返された名前（例：WI-000001）をレビュー作成コマンドに渡します
   • 組織に保存された VCS 認証情報を使用し、DevOps Center API 経由で PR を作成します
   • ローカルの VCS 認証は不要です。DevOps Center が GitHub／Bitbucket の認証を処理します
   • GitHub と Bitbucket に対応しています
   • コマンドがステータス 0（成功）を返すことを確認します
   • JSON 応答を解析します。.result.pullRequestUrl に PR の URL、.result.status に PR のステータス（新規作成の場合は通常「open」）、.result.number に PR 番号が含まれます
   • VCS 認証情報エラーでコマンドが失敗した場合は、DevOps Center 組織で VCS 認証情報を設定するようユーザーに案内します（Setup → DevOps Center → VCS Credentials）
   • 「PR already exists」エラーでコマンドが失敗した場合は、この作業項目の PR がすでに存在することを伝えます（冪等な操作）

Phase 3 — 検証と報告

8. 操作が成功したことを検証します：

   • リストの場合：CLI がステータス 0 を返したことを確認し、JSON の .result[] 配列を解析して、作業項目が含まれていること（または一致する項目がない場合は空であること）を確認します。ユーザーがプロジェクト名を指定した場合は、解決されたプロジェクト ID が一致することを確認します。
   • 作成の場合：CLI がステータス 0 を返したことを確認し、JSON 出力に .result.name（WI-000001 のような作業項目 ID）、.result.branch（ブランチ名）、.result.environment の各フィールドが含まれていることを確認します。
   • コミット（git パス）の場合：各 git コマンドが終了コード 0 を返したことを確認します。git push が成功した場合、コミットは作業項目のブランチに保存され、ハブには非同期で登録されます。
   • コミット（API パス）の場合：POST の status、続いて DevopsRequestInfo.Status が SUCCESS であることを確認し、CommitReference を含む新しい WorkItemComponentList がハブに存在することを確認します。CommitReference が空の新しいリストは、新しい内容が何もコミットされていないことを意味します。その場合は正常に成功したと報告せず、その旨を伝えます。
   • 更新（一般フィールド）の場合：CLI がステータス 0 を返したことを確認し、返された JSON フィールドをユーザーが指定した変更と比較します。サブジェクトを更新した場合は、.result.subject が新しい値と一致することを確認します。
   • 更新（ステータス遷移）の場合：CLI がステータス 0 を返したことを確認し、JSON 応答の .result.status が目標ステータス（例：「Ready to Promote」）と一致することを明示的に確認します。応答にステータスフィールドが含まれていない場合は、対象の作業項目に絞り込んで sf devops work-item list を再実行し、ステータスが反映されていることを確認します。
   • レビュー作成の場合：CLI がステータス 0 を返したことを確認し、JSON 出力に .result.pullRequestUrl（PR の URL）と .result.status（「open」または同等の値）が含まれていることを確認します。VCS の認証情報が不足している場合、CLI はエラーを返すため、その内容をユーザーに伝えます。

9. 結果を報告します：

   • リスト：作業項目名、サブジェクト、ステータス、ブランチ、環境を含め、読みやすい形式で作業項目を提示します。ステータスによる絞り込みが指定されている場合は、一致する作業項目のみを表示します。
   • 作成：作業項目名（例：WI-000001）、ブランチ名、環境を返し、「作業項目を正常に作成しました」と伝えます。
   • コミット：git パスの場合は、ステージングしたファイル、コミット SHA（git の出力から取得）、および「変更をコミットし、 ブランチにプッシュしました」と伝えます。API パスの場合は、reqId、コミットされたコンポーネント、ハブの CommitReference（作成者は DevOps Center）を伝えます。
   • 更新（一般）：変更されたフィールドを変更前と変更後の値とともに伝えます（例：「サブジェクトを『X』から『Y』に更新しました」）。
   • ステータス遷移：旧ステータスから新しいステータスへの遷移を明示します（例：「ステータスを更新しました：In Progress → Ready to Promote」）。
   • レビュー作成：PR の URL を返し、「プルリクエストを正常に作成しました。ステータス：open。URL：」と伝えます。

---

ルール／制約

制約	理由
すべての sf devops コマンドで --json フラグを使用する必要があります	ヘッドレス環境で処理するには構造化出力が必要です。人間向けの出力は解析に適していません
commit、update、create-review には作業項目識別子が必要です	--work-item-name（推奨）または --work-item-id を使用します。list または以前の create から取得してください
list と create にはプロジェクト ID が必要です	すべての作業項目はプロジェクトに属します。指定されていない場合は sf devops project list --json を使用します
少なくとも 1 つの更新フィールドが必要です	--subject、--description、--status のいずれのフラグも指定しないと、update コマンドは失敗します
ステータス値は正確な文字列で指定する必要があります	「In Progress」と「Ready to Promote」（スペースと大文字・小文字を正確に指定）を使用します。それ以外の値は失敗します
create 操作は冪等にします	重複を作成する前に、同じ subject と project を持つ作業項目がすでに存在するか確認します
PR を作成する前に commit します	最初に commit し、review create の前にハブにコンポーネントリストが存在することを確認します
API の commit で送信されるのは、開発組織内にすでにあるコンポーネントのみです	API はローカルディスクではなく開発組織から取得します。ローカルのみの編集は先にデプロイする（sf project deploy start）か、git のパスを使用します
commit API の応答で status を確認します	エラーは HTTP 200 と status: "ERROR" で返されます
PR の作成には、組織内の VCS 認証情報が必要です	DevOps Center API は保存済みの VCS 認証情報を使用します。ローカルの git 認証は不要です
対話型プロンプトは使用しないでください	スキルはヘッドレス環境で実行されます。すべての入力は CLI フラグで指定する必要があります

---

注意事項

問題	解決方法
デフォルト組織が設定されていない	最初に sf org display --json を実行します。失敗した場合は、sf org login web --set-default を実行するようユーザーに案内します
ユーザーが作業項目を名前ではなく subject で指定している	次のコマンドで解決します：sf devops work-item list --project-id <id> --json | jq -r '.result[] | select(.subject == "<subject>") | .name'。その後、返された名前を update/create-review コマンドに渡します
ユーザーがプロジェクトを ID ではなく名前で指定している	最初に sf devops project list --json を実行し、.result[] を .name フィールドで絞り込んでプロジェクト ID を特定します。その後、その ID を list/create コマンドで使用します
ステータス更新の応答に status フィールドがない	CLI は更新応答で status フィールドを常に返すとは限りません。この作業項目で絞り込んだ sf devops work-item list を再実行し、.result[0].status を確認して、ステータス変更が反映されたことを検証します
作業項目が見つからない	ユーザーが無効な作業項目名／ID を指定しています。list コマンドを実行して、利用可能な作業項目を表示します
無効なステータス値	有効なのは「In Progress」と「Ready to Promote」のみです（スペースと大文字・小文字を含め、正確に指定してください）。スペルと大文字・小文字を確認します
プロジェクトが見つからない	ユーザーが無効なプロジェクト ID を指定しています。sf devops project list --json を実行して、利用可能なプロジェクトを表示します
作業項目の subject が重複している	冪等な create チェックで検出されるはずです。重複を作成せず、既存の作業項目名を返します
作業項目が New の状態で commit が push された	ハブは New の作業項目に対する外部からの push を無視します。最初に In Progress に設定し、すでに push 済みの場合はステータス変更後に再確認します
期限を過ぎても API の commit が進行中のまま	停滞していると報告します。新しいリクエストが競合する可能性があるため、自動的に再試行しないでください
Git の push が失敗する（commit がない、またはブランチが見つからない）	git status でファイルがステージされていることを確認し、list コマンドで作業項目からブランチ名を取得します
PR の作成が VCS 認証情報のために失敗する	DevOps Center UI で VCS 認証情報が設定されていません。Setup → DevOps Center → VCS Credentials で設定するようユーザーに案内します

---

出力内容

操作に応じて、成果物は異なります。

• List：作業項目名（WI-######）、件名、ブランチ、環境、リポジトリの詳細を含む作業項目の JSON 配列
• Create：新しく作成された作業項目の作業項目名（例：WI-000001）、ID、ブランチ名、環境
• Commit：Git のコミットとプッシュが成功したことを示す確認とコミット SHA。API 経由の場合は、reqId、最終リクエストステータス、CommitReference
• Update：更新されたフィールドの確認（件名／説明の場合は変更前の値 → 変更後の値、またはステータスの変更）
• Create-review：プルリクエストの URL、PR 番号、ステータス

出力は、sf devops work-item CLI、sf devops review create CLI、標準の Git コマンドから取得されます。

---

検証チェックリスト

結果をユーザーに報告する前に、以下を確認してください。

共通チェック

• sf org display --json で組織の認証を確認しましたか？
• CLI コマンドに --json フラグを指定しましたか？
• CLI は正常終了コード（0）を返しましたか？
• JSON 出力は解析可能で、空ではありませんか？
• 複数組織のシナリオでは、すべてのコマンドに --target-org を指定しましたか？

List 操作のチェック

• --project-id を指定しましたか？
• 作業項目名、件名、ブランチ、環境を表示しましたか？
• リストが空の場合、その旨をユーザーに伝えましたか？

Create 操作のチェック

• JSON 出力に作業項目名（WI-######）と ID が含まれていましたか？
• JSON 出力にブランチ名が含まれていましたか？
• コマンドに --subject を指定しましたか？
• --project-id を指定しましたか（またはプロジェクトリストから取得しましたか）？

Commit 操作のチェック

• API 経由の場合：事前チェックに合格し、POST の status を確認し、DevopsRequestInfo を SUCCESS になるまでポーリングし、ハブ上で新しい WorkItemComponentList に CommitReference が含まれていることを確認しましたか？
• Git 経由の場合：作業項目が In Progress であることを確認し、ブランチ名を取得しましたか？
• Git 経由の場合：git add、git commit、git push がすべて終了コード 0 で完了しましたか？

Update 操作のチェック

• 作業項目の識別子（名前または ID）を指定しましたか？
• 少なくとも 1 つの更新フィールド（件名、説明、ステータス）を指定しましたか？
• ステータスを更新した場合、有効な値（"In Progress" または "Ready to Promote"）を指定しましたか？
• 更新後の作業項目が JSON で返されましたか？

Create-Review 操作のチェック

• 作業項目の識別子（名前または ID）を指定しましたか？
• JSON 出力に PR URL が含まれていましたか？
• PR の作成が確認されましたか？

---

参照ファイル一覧

ファイル	参照するタイミング
references/commit-api.md	DevOps Center API 経由でコミットする場合：リクエスト本文、レスポンスとエラーコード、ポーリング、事前チェック
references/cli-commands.md	CLI フラグの詳細なドキュメント、JSON 出力スキーマ、エラー処理パターンが必要な場合
examples/common-workflows.md	ユーザーのリクエストが一般的なパターン（複数項目の一括更新、再割り当て、冪等な作成、順次遷移）に該当する場合