フックはCoroidで発生する事象に反応します。該当するイベントを選択し、平易な言葉で指示を記述すれば、イベントが発生した際にフックが実行されます。
それらは自動化機能内の「自動化」セクションで確認できます。
新規作業で1つ作成します：自動化を選択し、次に「何かが発生したとき」を指定します。新規作業ではGitHubイベントとCoroidのイベントが利用可能です。詳細はこちらをご覧ください。自動化。
反応可能なイベント一覧
フックは特定の事象が送信したイベントに対してのみ実行されます。ほとんどの下記イベントはCoroid自体が送信しますが、一部は自社システムが発火させます。その他のイベントは予約済みとなっており、エディタには表示されず、該当するイベントで新しいフックを作成することもできません。予約済みのイベントで保存されたフックは、エディタと一覧で「実行不可」とマークされますが、削除されるわけではありません。
Coroidが送信するイベント
| カテゴリ | イベント |
|---|---|
| タスク | 作成済み、ステータス変更、完了、失敗 |
| エージェント | 開始、完了、エラー |
| リポジトリ | コミットのプッシュ、ブランチの作成、pull requestの開設・更新・マージ、課題の開設、Coroidを言及するコメント |
| スプリント | 作成済み、計画開始、開始、タスク追加、タスク削除、レビュー開始、完了、キャンセル |
| プラン | フェーズ開始、完了、失敗 |
| スケジュール | 実行開始、実行完了、実行失敗 |
| レポート | 開始、完了、失敗 |
| 品質 | チェック開始、合格または不合格、自動的に解決 |
| プロモーション | 要求済み、承認済み、却下 |
| リリース | 作成済み、候補変更、備考変更、備考承認、スコープ変更、チェックリスト完了、ゲート評価、ゲート上書き、承認済み、公開、ロールバック |
| デプロイ | キュー待ち、実行中、成功、失敗、キャンセル、手動で証明、手動でロールバック証明、ヘルスチェック合格、ヘルスチェック失敗 |
| 同期 | 外部ソースの更新 |
| SlackおよびTelegram | 自動化のフィルターに一致するメッセージ |
自社システムが発火させるイベント
| カテゴリ | イベント |
|---|---|
| 分析 | 依存関係の検出、セキュリティ問題の発見、分析完了 |
| 外部デプロイ | 開始、完了、失敗 |
Coroidはこれらのイベントを送信しません。CIパイプライン、スキャナー、または他の自社システムがIDを使ってフックを発火させ、以下のコマンドを呼び出します。POST /api/v1/organizations/hooks/:id/dispatchキー付きのサービスアカウントこれにはhooks:dispatchのスコープが設定されています。フックは保存されたイベントに対して実行されます。エディタではこれらのイベントを「自社システムが発火させるもの」として一覧表示します。
予約済みのイベント
これらはまだ送信または発火していないため、エディタでは選択できません：
| カテゴリ | イベント |
|---|---|
| タスク | フェーズ変更 |
| エージェント | 反復処理、ツール呼び出し |
| プラン | 作成済み、フェーズ完了、最終レビュー開始、最終レビュー完了、プランのpull request前 |
| スケジュール | 作成済み、有効化、一時停止 |
| スプリント | 計画完了、タスク完了、スコープ変更 |
| リリース | ステージング済み、検証済み |
| プロモーション | プロモーションのpull request前 |
| 品質 | チェック利用不可、修復開始または試み、再検証開始、合意形成 |
作業の開始と終了
プラン、スケジュール、レポート、品質チェック、プロモーション、リリースは開始時にイベントを、終了時に別のイベントを送信します。フックは作業の終了状況に反応でき、自社システムで作業に要した時間を測定することも可能です。
| 作業 | 開始 | 終了 |
|---|---|---|
| プラン | フェーズ開始：プランの実行開始時に最初のイベントが送信されます。 | 完了、失敗 |
| スケジュール | 実行開始 | 実行完了、実行失敗 |
| レポート | 開始 | 完了、失敗 |
| 品質チェック | チェック開始 | 合格、不合格、自動的に解決 |
| プロモーション | 要求済み | 承認済み、却下 |
| リリース | 作成済み | 公開、ロールバック |
これらのイベントはすべて、発生時刻をoccurredAt。作業の終了状況を報告するイベントでは、作業開始時刻もstartedAt、所要時間はdurationMs。それはstartedAt開始イベントのoccurredAt開始イベントと終了イベントは常に一致します。一時停止中に費やされた時間も作業時間に含まれます。
各イベントは変更が保存された時に一度だけ送信されます。取り消された変更では何も送信されず、再試行時にも二重に送信されません。終了イベントは開始された作業に対してのみ送信されます。スケジュールのドライランや開始前にキャンセルされたレポートでは送信されません。
各イベントが持つ情報は、時間以外に以下の通りです：
| イベント | 送信されるタイミング | フィールド |
|---|---|---|
| 計画フェーズが開始 | 計画の実行が開始されます（最初のフェーズ）。また、別のフェーズの最初のタスクが開始されるたびに送信されます。 | planId、plan(id, title),phase(id, sequence, title),firstPhase、executionStartedAt |
| 計画が完了または失敗 | 計画の実行が終了します。計画中に失敗した場合は送信されません。 | planId、plan、status、executionStartedAt |
| スケジュール実行が開始 | スケジュール実行が開始されます。 | scheduleId、runId、schedule(id, name),run(トリガー理由, 親実行履歴) |
| スケジュール実行が完了または失敗 | 実行が終了します。 | 同じフィールド、status、およびtasksCreatedまたはerror |
| レポートが開始 | レポートの生成が開始されます。一時停止や再開時でも開始時刻は変わりません。 | reportId、report(id, type, title) |
| レポートが完了または失敗 | レポートが保存されるか、失敗またはキャンセルされます。 | 同じフィールド、およびtokensUsed、costUsdおよびhasActionableFindings、またはerror |
| 品質チェックが開始 | 品質チェックが開始されます。 | qualityRunId、check(対象, トリガー, ポリシーバージョン, コミット) |
| 品質チェックが合格または不合格 | チェックが判定結果を出します。 | 同じフィールド、decision、redoCause、failedExpectationIds |
| 品質に関する問題が自動的に未解決 | Coroidはチェックで検出された問題の修復を試みるのを中止します。 | qualityRunId、workItemType、workItemId、reason |
| プロモーションが要求 | プロモーションが作成されます。 | promotionId、laneId、promotion(タイトル, ステータス, ブランチ, pull request) |
| プロモーションが承認 | プロモーションがマージされます：Coroidで承認され、強制マージ、プロバイダーでのマージ、またはリリースに含まれます。 | 同じフィールド、approval、approvedBy、forceReason |
| プロモーションが拒否 | レビュアーが変更を要求します。 | 同じフィールド、reason、requestedBy、comment |
| リリースが公開 | リリースの最初の本番環境へのデプロイが成功します。 | releaseId、version、commitSha |
| リリースがロールバック | ロールバックにより、環境内のリリースが置き換えられます。 | releaseId、version、rolledBackToReleaseId |
プロジェクト内の作業に関するイベントには以下も含まれますprojectId、そのため特定のプロジェクトに限定されたフックはそのプロジェクトに対してのみ発火します。フックが作業を作成した場合、これらのイベントはそのフックの連鎖深度にカウントされます。
トリガーと宛先
各自動化処理にはイベントが発生するトリガー元と、発火時に何を実行するかを決める宛先があります。そのうち2つの宛先はイベントを作業に変換します。
| トリガー元 | イベント |
|---|---|
| ワークフローイベント | Coroid内のイベントで、上記の表に記載されています。 |
| GitHub | プルリクエストが開かれた、更新された、またはマージされた場合、課題が開かれた場合、Coroidを言及するコメントが投稿された場合 |
| Slack | 自動化のフィルターに合致するメッセージ |
| Telegram | /coroidで始まるなど、自動化のフィルターに合致するメッセージ |
| Jira | 新しい課題 |
| 宛先 | 実行内容 |
|---|---|
| フック | このページに記載の通り、読み取り専用で指示を実行します。 |
| 作業を選定 | イベントを要求として記録します。選定が完了すると、Coroidが作業を作成します。 |
| Coroid Check | 廃止されました。すべてのpull requestに対するCoroidのレビューは「品質管理」に設定され、既存の自動化処理は一時停止されました。 |
GitHubのイベントにはGitHubアプリが必要です。Coroidを言及するコメントは、作者がリポジトリに書き込み権限を持つ場合にのみカウントされます。詳細はGitHub。
作業を選定するタスクは、イベントの作者が信頼できる場合にのみ自動的に開始されます。つまり、GitHubのpull request、課題、またはコメントの作者で、リポジトリに書き込み権限を持つ者です。Slack、Telegram、Jiraの作者は信頼されないため、彼らのタスクは誰かが開始するのを待ちます。詳細は作業が開始されるタイミング。
新しいJira課題は、CoroidのJira Webhookを通じてのみCoroidに届きます。Coroid用に設定されたWebhookシークレットで署名されたデータのみを受け付け、新規課題に対してのみ、かつ課題のJiraプロジェクトキーがCoroidのプロジェクトと一致する場合に限り処理されます。coroid.aiではまだJira Webhookが設定されていないため、Jiraトリガーはイベントを受信しません。その代わりにJira課題をインポートしてください。Webhookが設定されている場合、新規課題はJiraトリガー上の自動化処理に送られ、例えば「品質管理」内のJiraリクエストソースによって、指定した種類・優先度の課題が「Qualification」に登録されます。トリガー上に自動化処理が設定されていない場合、新規課題は何も登録されません。Jiraからの作業は自動的に開始されることはありません。詳細はこちらをご覧ください。課題追跡ツール。
デフォルトでは読み取り専用
フックは分析して報告します。後続の作業を作成することはできますが、コードを直接変更することはありません。
このデフォルト設定により、安全に導入できます。イベントに応じてコードを編集する自動化処理は、監視が最も行われにくいタイミングで実行されるからです。フックがタスクを作成する通常のプロセスと同じ結果を生み出します — 仕様定義、計画、検証、レビュー、pull request。
- スケジュール時間
- イベント駆動型の自動化何かが発生したとき
通常のタスク
仕様、計画、ビルド、検証、レビュー。エージェントスロットを利用し、より低い優先度を設定してください。
P2P3A pull request
自らマージしたり、ベースブランチにコミットしたりすることはできません。
あなたが承認します
適切な指示の書き方
フックの指示はモデルによって処理されるため、コードではなく同僚への指示のように記述されます。品質基準は通常の場合と同じです。仕様定義：何を確認すべきか、何が重要か、そして何をすべきかを明記します。
「何もしない」ケースについては具体的に記述してください。これが欠けると、フックは実行するたびに何かを出力してしまい、常に動作するフックは読まれなくなります。
ガードレール
イベント駆動型の自動化処理が予測可能な形で失敗するため、3つの保護機能が用意されています。
呼び出し制限分、時間、日単位でフックごとに設定可能です。頻繁に発生するイベントに対するフックは、繁忙期に何百回も呼び出される可能性があります。
チェーン深さフックがイベントを発行し、それが別のフックを呼び出すことがあります。最大チェーン深さを設定することで、ループが発生するのを防ぎます。
ツール権限フックがアクセスできる範囲は制御されており、読み取り専用アクセス、MCP呼び出し、タスク作成は個別に管理されます。
権限
フックを作成、変更、テスト、削除できるのはオーナーと管理者のみです。すべてのメンバーがフックとその実行履歴を確認できます。フックは組織全体に作用するため、この権限の違いは意図的なものです。
実行状況の確認
ファクトリーの各フックのページには、過去30日間の実行状況と処理内容（実行回数、失敗、コスト）が表示されます。すべての自動化の実行履歴は、設定 → アクティビティでも確認でき、「自動化」で絞り込めます。新しいフックを有効にしたら、実行状況を確認してください。問題なのはエラーではなく、何度も発火しても誰も対応しない結果しか生まないことです。
フックとスケジュール
| 仕組み | トリガー |
|---|---|
| フック | プラットフォームイベント |
| スケジュール | 時間 |
どちらも自動化で、ファクトリーにまとめて表示されます。詳しくは自動化。