mcpField
S
superplane-canvas-builder

superplane-canvas-builder

github.com/superplanehqクラウド・DevOps165 回インストール16 週間前に更新
リポジトリ

superplane-canvas-builder について

superplane-canvas-builderは、ワークフロー要件をSuperPlaneのcanvas YAMLに変換するスキルです。CLIでインテグレーション、トリガー、アクション、スキーマ、リソース値を確認してから、キャンバスを作成・更新する手順を示します。

主な機能

  1. 01要件からキャンバス YAML を作成
  2. 02CLIによるトリガーとアクションの検索
  3. 03インテグレーションとリソース値の検証
  4. 04グラフ接続とノード配置の指針
  5. 05式とペイロードの確認

活用シーン

  1. 01ワークフロー仕様からキャンバスを作成
  2. 02YAML生成前のインテグレーション確認
  3. 03実行ペイロードに基づく式の検証

インストール

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

$npx skills add https://github.com/superplanehq/skills --skill superplane-canvas-builder

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
components-and-triggers.md
daytona.md
github.md
sentry.md

詳細

SuperPlane Canvas Builder

ワークフロー要件を SuperPlane キャンバス YAML に変換します。

クイックリファレンス

タスクコマンド
アクションを一覧表示superplane index actions
インテグレーションのアクションを一覧表示superplane index actions --from <integration>
アクションの詳細を表示superplane index actions --name <name>
トリガーを一覧表示superplane index triggers --from <integration>
初期 YAML を生成superplane canvases init
キャンバスを作成superplane canvases create --file canvas.yaml
キャンバスを更新superplane canvases update <name-or-id> --draft -f canvas.yaml

操作の順序

必ず次の順序で進めてください。CLI を主な手段として使用してください。CLI では、ドキュメントでは確実に代替できない正確な名前、ID、スキーマを確認できます。

1. CLI と接続を確認する
command -v superplane

パスが出力されない場合は、そこで停止してください。CLI を https://docs.superplane.com/installation/cli からインストールして、タスクを再実行するようユーザーに伝えてください。ユーザーに代わってインストールしようとしてはいけません。ドキュメントに基づく設計へ暗黙に切り替えてはいけません。

次に、現在のセッションを確認します。

superplane whoami

認証、DNS、タイムアウト、接続の問題が原因で whoami が失敗した場合、CLI はインストールされていますが、セッションはまだ使用できません。必要に応じて、接続、コンテキストの修正、またはネットワークアクセスの許可をユーザーに依頼してください。CLI セッションが正常に動作するまでは続行しないでください。

まだ接続されていない場合：

superplane connect <URL> <TOKEN>
superplane whoami

接続情報を確認できない場合は、そこで停止し、接続するか、必要な URL とトークンを提供するようユーザーに依頼してください。CLI セッションが正常に動作するまでは続行しないでください。

1b. 変更をドラフトとして適用する

この環境では常にバージョン管理が有効です。モードの検出は行わず、すべての superplane canvases update コマンドで --draft を使用してください。

superplane canvases update <name-or-id> --draft --file canvas.yaml
2. ワークフローを把握する

検出コマンドを実行する前に、ワークフローに必要なものを特定します。

  • 何が開始のきっかけになりますか？ → トリガー（スケジュール、Webhook、GitHub のプッシュ、手動）
  • どのようなステップがありますか？ → 各ステップはアクションノードです
  • 判断が必要ですか？ → 分岐には If または Filter アクションを使用します
  • 待機が必要ですか？ → Approval、Time Gate、Wait アクションを使用します
  • どの外部システムを使用しますか？ → それぞれがプロバイダーに対応します（例：GitHub、Slack、Daytona）

この分析から必要なプロバイダーの一覧を作成してください。次のステップで確認します。

3. インテグレーションを検出して確認する

superplane integrations list を実行して、組織内で接続されているすべてのインテグレーションを取得します。ステップ 2 で特定した必要なプロバイダーと照合してください。

必要なプロバイダーが接続されていない場合： YAML を作成する前に停止し、ユーザーに伝えてください。例：

このキャンバスには GitHub と Daytona のインテグレーションが必要です。組織では GitHub は接続されていますが、Daytona は接続されていません。続行する前に、SuperPlane UI（設定 → インテグレーション）で接続してください。

組織が接続していないプロバイダーを参照する YAML を生成してはいけません。該当するすべてのノードで「integration is required」エラーが発生します。

すべてのプロバイダーの接続を確認したら、正確な名前とスキーマを検出します。

superplane integrations list                          # connected instances → real integration IDs
superplane index triggers --from <provider>           # exact trigger names
superplane index actions --from <provider>         # exact action names

必要な設定フィールド、出力チャネル、ペイロードの形状を確認します。

superplane index triggers --name github.onPush --output json
superplane index actions --name semaphore.runWorkflow --output json

integration-resource フィールドの実行時オプションを一覧表示します。

superplane integrations list-resources --id <id> --type <type>

YAML の作成・適用前に必ず確認すること： 設定するすべての integration-resource フィールド値（例：repository、snapshot、sandbox、project）について、そのインテグレーションの list-resources 出力に正確な値が存在することを確認してください。存在しない場合は停止し、使用する有効な値をユーザーに確認してください。

スキーマの優先ルール： プロバイダーの参考例と、CLI のスキーマ出力（superplane index ... --output json）または現在の list-resources の値が矛盾する場合は、CLI の出力に従ってください。参考資料は補助情報であり、CLI が信頼できる情報源です。

4. アクションを選択してグラフを接続する

ステップ 3 のトリガー名とアクション名を正確に使用してください。ドキュメントから推測してはいけません。

  • トリガーが組み込みのフィルタリング（コンテンツフィルター、アクションフィルター、ref フィルター）に対応している場合は、トリガーのレベルで設定します。トリガーのネイティブ設定では表現できないロジックが必要な場合にのみ、個別の Filter または If ノードを追加してください。
  • 各アクションには、少なくとも 1 つの入力エッジが必要です。
  • トリガーには入力エッジがありません。
  • 分岐には名前付きチャネルを使用します（If → true/false、Approval → approved/rejected）。
  • Filter は、式が true の場合にのみ default に出力します。false イベントは何も通知せずに停止します。
  • 並列分岐を合流させるには Merge を使用します。

全リストについては、コンポーネントとトリガーのリファレンスを参照してください。

5. ノードを配置する

各ノードには position: { x, y } が必要です。ノードのサイズは幅 515px × 高さ 215pxです。重なりを防ぐため、次の間隔ルールを使用してください。

方向増分理由
水平方向（x）列ごとに +600px幅 515px + 間隔 85px
垂直方向（y）行ごとに +300px高さ 215px + 間隔 85px

最初のノード（トリガー）は { x: 120, y: 100 } に配置します。

線形パイプライン — y は同じにして、x を増やします。

Trigger: { x: 120, y: 100 }  →  Step A: { x: 720, y: 100 }  →  Step B: { x: 1320, y: 100 }

分岐 — 分岐は同じ x 列に配置し、y 方向に広げます。分岐元のノードは、分岐に対して垂直方向の中央に配置します。

                                ┌─ Branch A: { x: 1320, y: 100 }
Source: { x: 720, y: 250 }  ───┤
                                └─ Branch B: { x: 1320, y: 400 }

ファンイン（Merge） — 分岐の次の x 列に配置し、y は分岐間の中央にします。

Branch A: { x: 1320, y: 100 } ──┐
                                 ├── Merge: { x: 1920, y: 250 }
Branch B: { x: 1320, y: 400 } ──┘

3 つ以上の分岐がある場合は、分岐ごとに y を 300 ずつ増やし、分岐元と Merge の位置をそれに応じて中央に調整します。

6. 式を設定する

式を書く前に必ず確認してください。 確認していないペイロードフィールドを参照する式を書いてはいけません。トリガー名やアクション名からフィールドパスを推測しないでください。

エンベロープ

各ノードの出力は、{ data: {...}, timestamp, type } というエンベロープでラップされます。次の 3 つのアクセスパターンはすべてこのエンベロープを返すため、実際のペイロードにアクセスするには、常に .data. が必要です。

パターン説明
$['Node Name'].data.field名前を指定して、上流にある任意のノードの出力にアクセスします
root().data.field実行を開始したルートイベントにアクセスします
previous().data.field直前の上流ノードの出力にアクセスします

よくある間違い： $['Create Sandbox'].data.id ではなく、$['Create Sandbox'].id と書いてしまうことです。必ず .data. を含めてください。

重要 — サンプルペイロードはすでにエンベロープを表しています。 superplane index triggers --name <trigger> が出力する（また、このスキルのリファレンスファイルに示されている）サンプルペイロードは、外側の { data: {...}, timestamp, type } を含む完全なエンベロープです。root().data は最上位の data オブジェクトを返します。その上に .data をさらに追加しないでください。正しい式を作るには、サンプル JSON 内の data キーを直接数えます。たどる必要のあるネストした data キーごとに .data を 1 つ使い、それ以上は追加しません。

ネストした data キー。 一部の Webhook（特に Sentry）では、ペイロード本体に独自の data フィールドが含まれています。そのため、正しいパスには .data が2 つ含まれます。root().data.data.issue.title が正しく、3 つではありません。root().data ですでにエンベロープを展開しており、2 つ目の .data は Webhook 独自の data フィールドをたどります。root().data.data.data.… と書いている場合は、エンベロープを重複して数えています。

設定フィールドの式には、二重波括弧 {{ }} を使用します。

{{ $['GitHub onPush'].data.ref }}
ペイロードのフィールドを確認する方法

次の情報源を順に確認し、利用可能な最初のものを使用してください。

  1. 既存の実行 — 過去の実行から実際のペイロードを確認します（最も信頼性が高い方法です）。

    superplane executions list --canvas-id <id> --node-id <nid> -o yaml

  2. このスキル内のプロバイダーのリファレンスファイル — 使用するプロバイダーの references/ ディレクトリを確認してください。ここにはペイロードの例と既知の注意点が記載されています。

  3. SuperPlane のドキュメント — LLM 向けドキュメントからプロバイダーのアクションページを取得してください。

最初の実行が成功したら、必ず情報源 1 に戻って、式を確認し、必要に応じて修正してください。トリガー名とペイロードの構造は一対一で対応するとは限らないため、トリガーがどのウェブフックイベントに対応するのか、必ずプロバイダーのリファレンスファイルまたはドキュメントで確認してください。

6b. コマンドノードのベストプラクティス

アクションでシェルコマンド（例：daytona.executeCommand、ssh）を実行する場合：

  • シェル文字列内で cd や export を使うのではなく、アクション固有の workingDirectory ／ envVars 設定を使用してください。これにより、引用符の処理が簡単になり、障害の発生しやすさを軽減できます。
  • 詳細な出力はファイルにリダイレクトし、簡潔なステータスマーカー（例：STEP_OK ／ STEP_FAILED）を標準出力に出力してください。標準出力が大きい場合やバイナリの場合、ノードの処理で問題が発生することがあります。
  • シェル実行モデル、堅牢化されたコマンドテンプレート、およびその連携に固有の既知の障害パターンについては、プロバイダーのリファレンスファイル（references/ ディレクトリ）を確認してください。
  • 複数のステップからなる長いスクリプトでは、bash -lc で空白や改行の解析に関する問題を避けるため、折りたたみ形式の 1 行文字列ではなく YAML のブロックスカラー（command: |-）を使用してください。
  • リリース前に手動でトリガーを 1 回実行し、実行 YAML 内のノードの outputs を確認して、想定するチャネルへのルーティング（success と failed）がエッジの配線と一致することを確認してください。
7. 適用

最初から作成する場合は、スターター YAML を生成します。

superplane canvases init --output-file canvas.yaml
# or start from a template:
superplane canvases init --template health-check-monitor --output-file canvas.yaml

次に、ファイルからキャンバスを作成するか、既存のキャンバスを更新します。

superplane canvases create --file canvas.yaml
# or update an existing canvas:
superplane canvases update <name-or-id> --draft --file canvas.yaml

YAML から新しいキャンバスを作成する場合、create --file はファイル内のグラフをすでに適用します。

superplane canvases create --file canvas.yaml

ワークフローのルール：

  • superplane canvases create --file canvas.yaml は、仕様に準拠したリソース形式の Canvas YAML（apiVersion、kind、metadata、spec）を受け付けます。
  • 作成後に superplane canvases update ... を実行するのは、metadata.id を含む後続のファイルや、create のデフォルトとは異なる明示的な自動レイアウトフラグなど、追加の変更を意図的に適用する場合に限ってください。
  • この環境では、すべての superplane canvases update ... コマンドに --draft を含めてください。

その後、確認します。

superplane canvases get <name>

いずれかのノードに errorMessage または warningMessage がないか確認してください。

8. 完了の定義（キャンバスの作成）

キャンバスを「準備完了」とする前に、次のすべてを確認してください。

  • superplane integrations list でインテグレーション ID が解決されている
  • すべての integration-resource 値が superplane integrations list-resources で確認されている
  • 意図した YAML ペイロードからキャンバスが作成されている
  • superplane canvases get <name> -o yaml ですべてのノードの errorMessage と warningMessage が空になっている
  • 少なくとも 1 回の実際のトリガー実行を確認し、重要な分岐ノードのチャネルレベルの outputs も確認している

よくあるパターン

直線：トリガー → A → B → C
nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 1320, y: 100 } }
  - { id: c, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: a, targetId: b, channel: default }
  - { sourceId: b, targetId: c, channel: default }
分岐：If → true ／ false
nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: check, ..., action: { name: if }, position: { x: 720, y: 250 } }
  - { id: on-true, ..., position: { x: 1320, y: 100 } }
  - { id: on-false, ..., position: { x: 1320, y: 400 } }
edges:
  - { sourceId: trigger, targetId: check, channel: default }
  - { sourceId: check, targetId: on-true, channel: true }
  - { sourceId: check, targetId: on-false, channel: false }
ゲート：Filter（通過または停止）

Filter は true の場合にのみ default に出力します。false のイベントは停止するため、エッジは不要です。

nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: filter, ..., action: { name: filter }, position: { x: 720, y: 100 } }
  - { id: next-step, ..., position: { x: 1320, y: 100 } }
edges:
  - { sourceId: trigger, targetId: filter, channel: default }
  - { sourceId: filter, targetId: next-step, channel: default }
ファンアウト／ファンイン
nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 720, y: 400 } }
  - { id: merge, ..., position: { x: 1320, y: 250 } }
  - { id: final, ..., position: { x: 1920, y: 250 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: trigger, targetId: b, channel: default }
  - { sourceId: a, targetId: merge, channel: default }
  - { sourceId: b, targetId: merge, channel: default }
  - { sourceId: merge, targetId: final, channel: default }
承認ゲート
nodes:
  - { id: ci-done, ..., position: { x: 120, y: 100 } }
  - { id: timegate, ..., position: { x: 720, y: 100 } }
  - { id: approval, ..., position: { x: 1320, y: 100 } }
  - { id: deploy, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: ci-done, targetId: timegate, channel: default }
  - { sourceId: timegate, targetId: approval, channel: default }
  - { sourceId: approval, targetId: deploy, channel: approved }

他のスキルを使用する場合

必要な内容使用するスキル
CLI コマンドと認証superplane-cli
失敗した実行のデバッグsuperplane-monitor

ドキュメント

URL を取得できるエージェント向けに、SuperPlane の全ドキュメントを LLM 向け形式で利用できます。

参考資料

  • アクションとトリガー — 組み込みのアクションとトリガーの種類
  • GitHub — トリガー、アクション、ペイロードの例、注意点
  • Daytona — アクション、ペイロードの例、注意点
  • Sentry — トリガー、ペイロードの例、入れ子になった data.data の注意点

コメント

Markdown 対応