オートパイロット

オートパイロットは、毎日の進捗まとめ、依存関係の定期確認、外部システムからイベントを受け取ったときの対応など、繰り返し発生する作業に使います。

各オートパイロットには、Runbook、実行担当、1 つ以上のトリガーが保存されます。トリガーされると、Multica はタスクを作成するか、エージェントを直接実行し、実行ごとの記録を残します。

オートパイロットを作成する

サイドバーからオートパイロットを開き、テンプレートを選ぶか、空の状態から作成して次を設定します。

• 名前: このオートパイロットが担当する作業
• Runbook: エージェントが実行ごとに読む目標、背景、制約、手順
• 実行担当: 1 つのエージェントまたはスクワッド
• 関連プロジェクト: 任意。自動作成したタスクを指定のプロジェクトに追加
• 出力モード: タスクを作成するか、実行のみ
• 購読者: 自動作成されたタスクの通知を受け取るメンバー
• トリガー: スケジュールまたは Webhook

保存すると、オートパイロットはデフォルトで有効になります。今すぐ実行を使えば、いつでも一連の処理を手動で 1 回実行できます。

出力モードを選ぶ

タスクを作成モードは、通常のタスクと同じ作業キューを使います。ランタイムがオフラインでも先にタスクを作成でき、作業はランタイムがオンラインになるまで待機します。

実行のみモードでは、トリガー時にランタイムが利用可能である必要があります。利用できない場合、その実行は「スキップ」と表示され、待機中のタスクは作成されません。

スケジュールで実行する

スケジュールエディターでは、実行時刻、繰り返す曜日、時間帯、タイムゾーンを指定し、次回以降の実行時刻をプレビューできます。1 つのオートパイロットに複数のスケジュールを追加できます。個別のトリガーを有効または無効にする場合は、CLI の autopilot trigger-update を使います。引数は CLI コマンドを参照してください。

より複雑なルールが必要な場合は、標準の 5 フィールド cron を直接編集できます。

分 時 日 月 曜日

例:

Cron に秒は含まれません。タイムゾーンには Asia/Shanghai のような IANA 名を使います。保存する前に、画面に表示される「次回」の時刻が意図どおりか確認してください。

Webhook で実行する

Webhook トリガーを追加すると、Multica が一意の URL を生成します。この URL に JSON オブジェクトまたは配列を送ると、オートパイロットをトリガーできます。

curl -X POST "$MULTICA_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{"event":"build.completed","eventPayload":{"status":"success"}}'

Payload は配信記録と実行記録に保存され、エージェントへ渡されます。タスク作成モードでは、イベントの内容がタスクの説明にも追加されます。

Webhook リクエストには次の制約があります。

• Body は有効な JSON オブジェクトまたは配列で、最大 256 KiB
• Idempotency-Key を使うと、送信側の再試行による重複実行を防止可能。GitHub の場合は X-GitHub-Delivery も重複排除に使用
• 安定した冪等キーがない場合、Multica は同じリクエストが 1 回だけ実行されることを保証できない
• トリガーが無効、またはイベントがフィルターに一致しない場合、配信は「無視」として記録され、実行は作成されない

イベントをフィルターする

同じ送信元から複数種類のイベントが届く場合、トリガーにイベントフィルターを追加できます。各行にイベント名と、任意で action の一覧を指定します。いずれか 1 行に一致すると実行され、すべて空の場合は全イベントを受け入れます。

たとえばイベント名に workflow_run、Actions に completed, failed を指定すると、この 2 種類の workflow_run の結果だけを受け取ります。Multica は一般的なリクエストヘッダーと payload からイベントと action を判定します。GitHub の X-GitHub-Event と body の action にも対応しています。

Webhook URL を保護する

完全な URL を確認できるのは、オートパイロットの作成者、ワークスペースの owner/admin、管理アクセスを付与された共同管理者だけです。画面では URL の token がデフォルトで隠されています。コピーするために表示する必要はありません。URL または目のアイコンをクリックすると完全なアドレスを確認できます。

Webhook レスポンス早見表

送信側をデバッグするときは、次の表で Multica のレスポンスを確認してください。

一時停止、アーカイブ、イベントフィルターなど、業務上の理由で無視した場合は 4xx ではなく 200 を返します。送信側が繰り返し再試行するのを防ぐためです。

イベントと action は次の順番で判定します。

1. body に文字列の event フィールドがあれば、その値を使用
2. なければ X-GitHub-Event リクエストヘッダーを確認し、body の action と組み合わせて github.<event>.<action> を生成
3. 次に X-Gitlab-Event リクエストヘッダーを確認
4. 次に X-Event-Type リクエストヘッダーを確認
5. 次に body の event、type、action フィールドを確認
6. どれもない場合は webhook.received

実行と配信の履歴を確認する

実行履歴には、トリガー元、時刻、状態、関連するタスクまたは作業、失敗やスキップの理由が表示されます。Webhook トリガーでは、解析したイベント、レスポンス、重複排除情報、失敗理由を含む個別の配信履歴も保存されます。

処理済みの Webhook 配信は詳細画面からリプレイできます。リプレイすると新しい配信と実行が作成され、元の記録は変更されません。署名検証に失敗した配信や、まだキューにある配信はリプレイできません。また、リプレイは重複排除の対象外です。

失敗、一時停止、削除

実行のみモードの作業が失敗しても、自動では再試行しません。次回のスケジュールは予定どおりトリガーされます。タスク作成モードで作成した作業は通常のタスクの作業として扱われ、インフラ障害時は作業のルールに従います。

Multica は最近の実行が継続的に失敗していないか定期的に確認します。過去 7 日間に完了または失敗した実行が 50 回以上あり、失敗率が 90% 以上の場合、オートパイロットを一時停止して作成者へ通知します。原因を修正した後、手動で再開できます。

手動で一時停止すると、スケジュール、Webhook、「今すぐ実行」がすべて停止します。削除は実際にはアーカイブであり、今後のトリガーは停止しますが、実行履歴と配信履歴は保持されます。

管理権限

• ワークスペースのすべてのメンバーがオートパイロットを作成可能
• 作成者とワークスペースの owner/admin は、編集、実行、削除、トリガーの管理が可能
• 作成者と owner/admin は、共同管理者を「管理アクセス」に追加可能
• 共同管理者は、編集、実行、トリガーの管理ができるが、ほかのユーザーへ権限を付与することは不可
• オートパイロットを管理できても、使用するエージェントを実行できるとは限らない。エージェントの Access は引き続き適用

CLI を使う

multica autopilot get <autopilot-id> --output json
multica autopilot trigger <autopilot-id>
multica autopilot runs <autopilot-id>
multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>

autopilot get はデフォルトで webhook_token、webhook_path、webhook_url を null にし、代わりに has_webhook_token と webhook_token_hint を返します。実際の認証情報が必要な場合に限り --show-secrets を追加してください。CLI は警告を stderr に出力するため、パイプされた JSON は有効なままです。

すべての引数は CLIを参照してください。

次のステップ

• タスクをエージェントに割り当てる — 割り当てと確認ダイアログ
• インボックスと購読 — 実行通知の受信先
• 作業 — 実行状態と失敗時の処理