dx-devops-pipeline-manage

DevOps Center パイプライン管理

DevOps Center のパイプラインライフサイクル全体を管理します。リポジトリを指定した作成から、ステージと環境の設定、プロジェクトの関連付けを経て、リリースを昇格できる状態のパイプラインを有効化します。自律的なリリースワークフローに対応する、ヘッドレスな CLI 駆動の操作を提供します。

対象範囲

• 対象：パイプラインの一覧表示、詳細の取得、パイプラインの作成（既存または新規の Git リポジトリへのリンク）、ステージの追加／削除／名前変更、ステージ上の Salesforce 環境の追加／削除、プロジェクトの関連付け／解除、パイプラインの有効化／無効化／名前変更
• 対象外：作業項目のライフサイクル、昇格／デプロイの実行、競合の検出、単独のプロジェクト作成（別のスキル）

---

必須入力

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

• 操作の種類：list、get、create、add-stage、delete-stage、rename-stage、add-environment、delete-environment、attach-project、detach-project、activate、deactivate
• get／ステージまたは環境の各操作：パイプライン ID（必須）— sf devops pipeline list --json で取得します
• create：パイプライン名（必須）と Git リポジトリ（--repo、必須）。シナリオによってリポジトリのフラグが異なります。
  • 既存のリポジトリ（GitHub または Bitbucket）：--repo <url> のみ — --repo-type／--create-repo は指定しないでください
  • 新しい GitHub リポジトリ：--repo <name> --create-repo --repo-type github --repo-owner <org-or-user>
  • 新しい Bitbucket リポジトリ：--repo <name> --create-repo --repo-type bitbucket --bitbucket-workspace <workspace>（--bitbucket-project-key <key> は任意）
  • 説明（--description）はいずれの場合も任意です
• add-stage：パイプライン ID、新しいステージ名、--next-stage-id（新しいステージの直後に配置するステージ）— sf devops pipeline get でステージ ID を取得します
• add-environment：パイプライン ID、ステージ ID、環境名、--org-type（Production または Sandbox）
• attach-project／detach-project：パイプライン ID とプロジェクト ID
• activate／deactivate／rename：パイプライン ID

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

• 出力形式：ヘッドレスでの使用には --json
• 対象組織：デフォルトの組織を使用しない場合は --target-org <alias>

ユーザーから明確な依頼（「リポジトリ myorg/myrepo にパイプラインを作成」「Production の前に UAT ステージを追加」「パイプライン 0XB... を有効化」など）があれば、不要な質問をせずに直ちに進めてください。

---

ワークフロー

すべての操作では sf devops pipeline および sf devops stage CLI コマンドを使用し、構造化データとして処理できるように --json を指定します。パイプライン ID とステージ ID が主な識別子です。変更を行う前に、list と get で ID を特定してください。

フェーズ 1 — 操作の特定

1. ユーザーの意図から操作の種類を判断します。
   • 「list」「show all pipelines」→ list、「details of pipeline」「show stages」→ get
   • 「create」「set up」「new pipeline」→ create
   • 「add stage」「insert stage」→ add-stage、「rename stage」→ rename-stage、「remove/delete stage」→ delete-stage
   • 「connect environment」「add org to stage」→ add-environment、「remove environment」→ delete-environment
   • 「attach project」「connect project」→ attach-project、「detach project」→ detach-project
   • 「activate」「turn on」→ activate、「deactivate」「turn off」→ deactivate、「rename pipeline」→ ライフサイクルの更新

フェーズ 2 — 操作を実行する

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

   sf org display --json
   

   • デフォルト組織が設定されていない場合、または認証の有効期限が切れている場合は、sf org login web --set-default --alias <alias> を実行するようユーザーに案内します
   • sf devops pipeline list --json を実行して、組織で DevOps Center が有効になっていることを確認します
   • 特定の組織を対象にする場合は、すべてのコマンドに --target-org <alias> を追加します

3. パイプラインを確認します：

   sf devops pipeline list --json                              # all pipelines in the org
   sf devops pipeline get --pipeline-id <pipeline-id> --json   # one pipeline, with stages/repos/projects
   

   • list は .result.pipelines[] の下に大文字始まりのフィールド（.Id、.Name、.IsActive）を持つ SObject レコードを返します。ステージや接続済みプロジェクトは含まれません
   • get は .result の下に camelCase のフィールド（.id、.name、.stages[]、.connectedProjects[]）を持つ単一のパイプラインを返します。各ステージには .id、.name、.nextStageId、.branchName、.environment.{id,name} があります。ステージはリンクリストです。順序は nextStageId で定義され、最後のステージの nextStageId は null です。ステージまたは環境に関する操作の前に、get を使用してステージ IDを確認します

4. パイプラインを作成します — パイプラインは Git リポジトリにリンクされている必要があります。--name と --repo は常に必須です。その他のフラグはリポジトリのシナリオによって異なります：

   # Existing repo (GitHub or Bitbucket) — pass the full repo URL, nothing else
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> --json
   
   # New GitHub repo — requires --repo-owner
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
     --create-repo --repo-type github --repo-owner <org-or-user> --json
   
   # New Bitbucket repo — requires --bitbucket-workspace (--bitbucket-project-key optional)
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-name> \
     --create-repo --repo-type bitbucket --bitbucket-workspace <workspace> \
     --bitbucket-project-key <key> --json
   
   # Custom stage chain (any scenario) — repeat --stage in promotion order
   sf devops pipeline create --name "<pipeline-name>" --repo <repo-url> \
     --stage Dev --stage QA --stage Prod --json
   

   • プロバイダー固有の必須フラグ：GitHub の新規リポジトリ → --repo-owner、Bitbucket の新規リポジトリ → --bitbucket-workspace。プロバイダーの必須フラグを省略すると、作成に失敗します
   • 既存のリポジトリでは --repo-type／--create-repo を渡さないでください。--repo でリポジトリの URL のみを指定します
   • 作成時のカスタムステージ：新しいパイプラインでは、デフォルトのステージチェーン Integration → UAT → Staging → Production が設定されます。異なるステージを設定するには、昇格順にステージごとに -s/--stage を指定します（例：--stage Dev --stage QA --stage Prod）。これにより、後からステージを追加／名前変更せずに済みます
   • どのシナリオでも、任意で --description "<text>" を追加できます
   • 後続のステージ／環境／プロジェクト／有効化の手順で使用するため、返されたパイプライン ID を保存します
   • 冪等性：CLI は重複を排除しません。作成前に sf devops pipeline list --json を実行し、同じ名前／リポジトリのパイプラインがないか確認します。見つかった場合は既存のものを返します。確認してから作成するスニペットは references/parsing-patterns.md を参照してください

5. ステージを設定します — ステージは既存のステージを基準に追加し、その後、環境に関連付けます。複数のステージを扱う前に、フラグの詳細について references/cli-commands.md を確認してください：

   # Insert an empty stage BEFORE an existing stage (get the next-stage-id from `pipeline get`)
   sf devops pipeline stage add --pipeline-id <id> --name "<stage-name>" --next-stage-id <stage-id> --json
   # Rename a stage
   sf devops pipeline stage update --pipeline-id <id> --stage-id <stage-id> --name "<new-name>" --json
   # Delete a stage (predecessor auto-relinks to successor)
   sf devops pipeline stage delete --pipeline-id <id> --stage-id <stage-id> --json
   

   • stage add は --next-stage-id の前に空のステージ（ブランチ／環境なし）を挿入します。環境は別途設定します
   • 後に続くべきステージの前に各新規ステージを挿入して、昇格チェーンを構築します

6. ステージに環境を関連付けます — Salesforce 組織をステージに接続します：

   # Validate the org-type against the fixed enum BEFORE calling the CLI
   bash scripts/validate-org-type.sh "<Production|Sandbox>"   # exits non-zero on an invalid value
   sf devops stage environment add --pipeline-id <id> --stage-id <stage-id> \
     --environment-name "<env-name>" --org-type <Production|Sandbox> --json
   # Remove an environment (pipeline must be inactive)
   sf devops stage environment delete --pipeline-id <id> --environment-id <env-id> --json
   

   • --org-type は Production または Sandbox のいずれかでなければなりません。まず scripts/validate-org-type.sh <value> を実行し、終了コードが 0 の場合にのみ続行します
   • ヘッドレス環境での注意事項：stage environment add は OAuth のブラウザーフローを開始します。ヘッドレス／CI 実行では --no-browser を渡してください。CLI は手動認証用のリダイレクト URL を出力します

7. プロジェクトを接続／切断します — プロジェクトを接続できるパイプラインは 1 つだけです：

   sf devops pipeline project add --pipeline-id <id> --project-id <project-id> --json
   sf devops pipeline project delete --pipeline-id <id> --project-id <project-id> --json
   

   • ユーザーが ID ではなくプロジェクト名を指定した場合は、sf devops project list --json を使用して解決します（references/parsing-patterns.md を参照）

8. パイプラインを有効化／無効化／名前変更します：

   # Before activating, confirm the deterministic ≥1-stage prerequisite
   bash scripts/check-activation-ready.sh <id> [target-org]   # exits non-zero if stage-less
   sf devops pipeline update --pipeline-id <id> --activate --json             # activate
   sf devops pipeline update --pipeline-id <id> --deactivate --json           # deactivate
   sf devops pipeline update --pipeline-id <id> --name "<new-name>" --json    # rename
   

   • --activate の前に scripts/check-activation-ready.sh <id> を実行し、終了コードが 0 の場合にのみ続行します。パイプラインにステージがない場合、このスクリプトは実行可能な対処方法を示すメッセージとともに失敗します
   • パイプラインを有効化して変更がそのパイプラインを通じて昇格された後は、ステージを変更できません。有効化する前に、ステージ／環境の設定を完了してください
   • --activate と --deactivate は同時に指定できません。--deactivate と --name は 1 つのコマンドで組み合わせることができます

フェーズ 3 — 検証と報告

9. 操作の成功を検証する — scripts/verify-operation.sh を使用します。このスクリプトは決定論的な JSON ステータスと操作後のフィールドをチェックし、不一致がある場合は対処方法を示すメッセージを出してゼロ以外の終了コードで終了します：

   # Assert a captured command's JSON status is 0 (pipe the CLI output in)
   sf devops pipeline update --pipeline-id <id> --activate --json | bash scripts/verify-operation.sh status -
   # Assert post-state after activate / stage / project ops
   bash scripts/verify-operation.sh active      <id> true         [target-org]   # isActive == true
   bash scripts/verify-operation.sh has-stage   <id> "<stage>"    [target-org]   # stage present in chain
   bash scripts/verify-operation.sh has-project <id> "<project>"  [target-org]   # project connected
   

   • 作成：sf devops pipeline list --json にパイプラインが .Name で表示されることを確認し、.Id を取得します
   • ステージ／環境／プロジェクトの変更：上記の has-stage／has-project モードで検証します（sf devops pipeline get を読み込み、.result.stages[]／.result.connectedProjects[] をチェックします）
   • 有効化：active <id> true モードで検証します

10. 結果を報告する：

    • 一覧表示：パイプラインごとに、名前、ID、有効状態を報告します（ステージは含めません。ステージの確認には get を使用します）
    • 取得：パイプライン名、ID、有効状態、ステージチェーン（各ステージの名前 → 環境 → ブランチを nextStageId に基づいて並べたもの）、接続済みプロジェクト
    • 作成：パイプライン ID、名前、リンクされたリポジトリ（冪等性の一致により既存のパイプラインが返された場合は「既存のパイプラインが返されました」）
    • ステージ／環境／プロジェクトの操作：各ステージの環境を含む、プロモーション順の結果のステージチェーン
    • ライフサイクル：新しい有効状態および／または名前

検証チェックリスト（成功を報告する前のゲート）

実行した操作に該当する項目を確認してください。該当するすべての項目を満たすまで、成功を報告してはいけません：

• すべての sf devops コマンドを --json 付きで実行し、status: 0 が返されている（scripts/verify-operation.sh status -）
• 作成：新しいパイプラインが sf devops pipeline list --json に名前で表示され、新しいリポジトリの場合はプロバイダー固有のフラグ（GitHub の場合は --repo-owner、Bitbucket の場合は --bitbucket-workspace）が指定されている
• ステージの追加／環境の追加：ステージがチェーンに存在し、--org-type が scripts/validate-org-type.sh に合格している（scripts/verify-operation.sh has-stage ...）
• プロジェクトの接続：プロジェクトが .result.connectedProjects[] に表示されている（scripts/verify-operation.sh has-project ...）
• 有効化：事前に scripts/check-activation-ready.sh に合格し、.result.isActive が現在 true である（scripts/verify-operation.sh active <id> true）
• 環境の削除：削除前にパイプラインが無効だった

---

ルール／制約

制約	理由
すべての sf devops コマンドで --json フラグを使用する必要があります	ヘッドレス環境で利用するには構造化出力が必要です。人間向けの出力は解析の信頼性に欠けます
パイプラインの作成時には Git リポジトリが必要です	sf devops pipeline create には --name と --repo が必要です。既存のリポジトリの場合は URL のみを渡し、新しいリポジトリの場合は --create-repo と --repo-type を追加します
新しいリポジトリの作成にはプロバイダー固有のフラグが必要です	GitHub では --repo-owner が必要です。Bitbucket では --bitbucket-workspace が必要です（--bitbucket-project-key は任意）。誤ったプロバイダーのフラグを指定すると、コマンドは失敗します
get、update、およびすべての stage／environment／project 操作にはパイプライン ID が必要です	これらのコマンドは --pipeline-id のみでパイプラインを特定します。sf devops pipeline list で取得してください
ステージ ID は pipeline get で取得します	stage add（--next-stage-id）、stage update／delete（--stage-id）、stage environment add（--stage-id）はいずれもステージ ID が必要です
stage add は --next-stage-id の前に空のステージを挿入します	ステージには環境が追加されるまで環境がありません。後続のステージを基点としてチェーンを構築してください
--org-type は Production または Sandbox のいずれかを正確に指定する必要があります	このフラグは固定列挙値です。それ以外の値では失敗します
有効化する前に、パイプラインに 1 つ以上のステージが必要です	ステージのないパイプラインに対して sf devops pipeline update --activate を実行すると拒否されます
有効化して昇格した後は、ステージを変更しないでください	DevOps Center は、有効なパイプラインで変更が昇格されると、ステージ構成をロックします
環境を削除するには、パイプラインが無効である必要があります	stage environment delete はパイプラインが無効な場合にのみ成功します
プロジェクトを追加できるパイプラインは 1 つだけです	プロジェクトがすでに別のパイプラインに追加されている場合、pipeline project add は失敗します。先に切り離してください
存在確認後に作成して冪等性を確保します	CLI は重複を排除しません。既存のパイプラインを一覧表示し、エラーにする代わりに一致するものを返してください
ヘッドレス環境では --no-browser を優先してください	stage environment add は OAuth ブラウザーフローを開きます。--no-browser を指定すると、CI 用のリダイレクト URL が出力されます

---

注意事項

問題	解決方法
デフォルトの組織が設定されていない	まず sf org display --json を実行してください。失敗した場合は、sf org login web --set-default を実行するようユーザーに案内してください
作成に失敗する — リポジトリが指定されていない	--repo は必須です。既存のリポジトリ URL を渡すか、新しいリポジトリの場合は --create-repo と --repo-type を指定してください
新しいリポジトリの作成に失敗する — プロバイダーのフラグが指定されていない	GitHub の新しいリポジトリには --repo-owner が必要です。Bitbucket の新しいリポジトリには --bitbucket-workspace が必要です。プロバイダーのフラグを混在させないでください（bitbucket に --repo-owner を指定する、または github に --bitbucket-workspace を指定するなど）
stage add が失敗する — next-stage-id が指定されていない	--next-stage-id は必須です。sf devops pipeline get --pipeline-id <id> --json を実行してステージ ID を確認し、新しいステージを挿入する位置のステージを選択してください
CI で環境の追加が停止する	OAuth ブラウザーフローによってヘッドレス実行がブロックされています。--no-browser を追加し、出力されたリダイレクト URL を使って認証を完了してください
有効化が拒否される	パイプラインには少なくとも 1 つのステージが必要です。--activate の前に、ステージとその環境を追加してください
ステージを変更できない	パイプラインは有効で、変更がすでに昇格されています。ステージ構成はロックされています。設定は有効化する前に完了してください
環境の削除に失敗する	パイプラインは有効です。環境を削除する前に、pipeline update --deactivate で無効化してください
プロジェクトはすでに追加されています	プロジェクトを追加できるパイプラインは 1 つだけです。まず pipeline project delete で別のパイプラインから切り離してください
パイプライン／ステージ／プロジェクトが見つからない	ID が無効です。有効な ID を見つけるには、sf devops pipeline list --json、sf devops pipeline get --json、または sf devops project list --json を実行してください

---

出力の想定

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

• List：ID、名前、有効状態を含むパイプライン（リスト表示にはステージ／プロジェクトは含まれません）
• Get：ID、名前、有効状態、ステージチェーン（それぞれ環境とブランチを含み、nextStageId による順序付き）、接続されているプロジェクトを含むパイプライン
• Create：パイプライン ID、名前、リンクされたリポジトリ（一致する既存のパイプラインがある場合はそのパイプライン）
• Stage op：更新後の順序付きステージチェーン
• Environment op：バインドされた環境を含むステージ（名前、組織タイプ）
• Project op：アタッチ／デタッチの確認
• Lifecycle：新しい有効状態および／またはパイプライン名

出力は sf devops pipeline および sf devops stage CLI コマンドから取得します。

---

スキル間の連携

委任先	使用する状況
dx-devops-work-item-manage	パイプラインが有効になった後、ユーザーが作業項目の作成または進行を希望する場合

アタッチしたいプロジェクトが見つからない場合は、委任せずに sf devops project list --json を使って既存のプロジェクトを検索または一覧表示します（references/parsing-patterns.md を参照）。プロジェクトの作成はこのスキルの対象外です。

---

参照ファイル一覧

ファイル	読み込むタイミング
references/cli-commands.md	各 sf devops pipeline ／ sf devops stage コマンドの CLI フラグの詳細なドキュメントと JSON 出力スキーマが必要な場合
references/parsing-patterns.md	JSON を解析する jq スニペット（ステージチェーン、パイプライン／プロジェクト ID の解決）、エラー処理のリファレンス、作成前確認による冪等パターン、または認証要件が必要な場合
examples/common-workflows.md	ユーザーのリクエストが一般的なパターン（パイプラインのエンドツーエンドの設定、ステージの挿入、環境のバインド、プロジェクトのアタッチ、有効化）に該当する場合
scripts/validate-org-type.sh	stage environment add の実行前に、--org-type が Production／Sandbox 列挙値に対して有効かを検証する場合
scripts/check-activation-ready.sh	pipeline update --activate の実行前に、パイプラインに 1 つ以上のステージがあることを確認する場合
scripts/verify-operation.sh	Phase 3 で実行し、コマンドの JSON ステータスと実行後の状態フィールド（status ／ active ／ has-stage ／ has-project）を検証する場合