リポジトリ変更の抽出・検証・人によるレビューを行う、信頼性の高いn8nワークフローを構築する

安全な基本方針：まず抽出し、チェック後にのみ操作する

リポジトリのワークフローで、AIエージェントにコードの編集やマージを無制限に許可しないでください。n8nでプルリクエストのメタデータとdiffを取得し、モデルに制約付きの要約を依頼して、応答を検証し、テスト状況を確認します。その後で初めて、プルリクエストのマージなど、影響の大きい操作を人の承認ステップに回します。

この分離が重要なのは、もっともらしい要約が変更内容の正しさを証明するわけではなく、モデルが正常に応答したこともテストの合格を意味しないからです。情報の抽出、検証、承認は、それぞれ独立したゲートとして扱ってください。

以下の設計は説明用であり、テスト済みのn8nエクスポートではありません。ノード名や利用できるフィールドは、n8nのバージョン、リポジトリプロバイダー、使用するモデルAPIによって異なります。デプロイ前に、関連するノードのドキュメントとパラメーターへの対応状況を確認してください。

前提条件

• リポジトリプロバイダーと、利用予定のモデルエンドポイントの認証情報を設定したn8nワークフロー。
• プルリクエストイベント用のトリガー、または初期テスト用の手動トリガー。
• テスト結果を報告できる、リポジトリのブランチ保護またはCIプロセス。
• 承認が必要なツールをワークフローが呼び出す場合、人による承認を行うレビュアー向けチャネル。
• 対象とするファイル、操作、リポジトリを定めたポリシー。

まずは読み取り専用のワークフローから始めてください。シークレット、環境設定ファイル全体、または無関係なリポジトリの内容を抽出ステップに渡さないでください。diffはプルリクエストで変更されたファイルに限定し、ペイロードの最大サイズを設定します。サイズを超える変更は分割するか、手動レビューに回してください。

抽出と検証のフローを構築する

実用的な処理の流れは次のとおりです。

1. トリガーと取得： プルリクエストIDを受け取り、リポジトリプロバイダーからタイトル、ベースとヘッドのリビジョン、変更ファイル一覧、diffを取得します。
2. フィルタリング： リポジトリが許可されていない場合、diffがサイズ制限を超える場合、または機密性の高いパスが含まれる場合は、処理を停止するか、手動対応に回します。
3. 抽出： レビューを補助する事実だけを含む小さなJSONオブジェクトをモデルに出力させます。たとえば、変更の要約、影響を受ける領域、明記されたリスク、人による確認が必要な質問などです。テスト結果を捏造したり、コードの安全性を断言したりしないよう指示します。
4. 解析と検証： 応答を解析し、必須フィールドと型をCodeノードなどの検証ステップで確認します。無効な出力は、アクションノードに渡さず、制御されたエラー分岐に送ります。
5. 確認： プロバイダーのチェック結果またはCIステータスを、正確なヘッドリビジョンについて照会します。必要なチェックがすべて完了し、成功している場合に限って次へ進みます。チェックが存在しない、または保留中である状態は合格ではありません。
6. レビュー： 検証済みの要約、PRリンク、リビジョン、チェック結果を人に提示します。マージなど書き込み可能なツールは承認の後ろに置きます。

以下は、抽出結果のスキーマ例です。これはワークフロー上の契約を示すものであり、すべてのモデルエンドポイントがスキーマ制約付きのネイティブ出力に対応しているという意味ではありません。

{
  "type": "object",
  "required": ["summary", "affected_areas", "risk", "review_questions"],
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "affected_areas": {
      "type": "array",
      "items": { "type": "string" }
    },
    "risk": { "enum": ["low", "medium", "high", "unknown"] },
    "review_questions": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "additionalProperties": false
}

エンドポイントがこのスキーマを強制できない場合は、応答後に検証してください。また、実用的な制限も設けます。想定外のフィールドを拒否し、文字列と配列の長さに上限を設定し、解析または検証に失敗した場合はワークフローをフェイルクローズにします。欠落した値を安心感を与えるデフォルト値で黙って置き換えないでください。

不正なデータではなく、一時的な障害を再試行する

タイムアウトやレート制限など、一時的な原因でリクエストが失敗した場合には再試行が有効です。待機時間を設けたうえで、回数を制限して再試行し、上限に達した失敗は、プルリクエストIDと失敗理由を記録するエラー分岐に送ります。無限ループは避けてください。

すべてのエラーを自動的に再試行しないでください。不正なJSON応答、必須フィールドの欠落、未対応パラメーター、無効な認証情報には、別の対応が必要です。処理を停止してエラーを記録し、リクエストを修正するか、人による確認を求めます。同じ無効なリクエストを繰り返しても、時間を浪費するだけで結果が改善しないことがあります。

再現性のある実行のため、ワークフローの記録はリポジトリ、プルリクエスト、ヘッドリビジョンをキーにして管理します。書き込み操作の前には現在のリビジョンを再取得し、ステータスを確認してください。抽出やテストの後にプルリクエストが更新されていた場合は、古い結果を無効にしてチェックをやり直します。これにより、あるリビジョンへの承認が別のリビジョンに適用されるのを防げます。

影響の大きいツールに人の承認を追加する

n8nでは、AI Agentが選択したツールを実行する前に、人による承認を必須にできます。ドキュメントに記載されたフローでは、ワークフローを一時停止し、設定済みのチャネルから承認リクエストを送信します。レビュアーが承認した場合にのみ、提案された入力でツールを実行し、拒否された場合は操作をキャンセルします。接続されたすべてのツールにレビューを適用することも、選択したツールだけに適用することもできます。詳しくは、n8nのhuman-in-the-loopドキュメントをご覧ください。

リポジトリのワークフローでは、抽出とステータス確認を読み取り専用にし、マージ可能なツールをレビューの後ろに配置します。レビュアーには、PRのURL、正確なヘッドリビジョン、検証済みの要約、テスト状況、ツールのパラメーターを提示してください。n8nのドキュメントでは、承認メッセージの作成に$tool.nameと$tool.parametersを使う方法が説明されています。これらのパラメーターを読みやすいリクエストに含めますが、リビジョンとCIステータスの確認を承認プロンプトの代わりにしてはいけません。

エージェントへの指示には、どのツールに承認が必要か、拒否された場合にどうなるか、その後エージェントが何をすべきかを明記します。拒否された場合はマージ経路を終了し、PRを議論や修正のために残します。許可を得ずに別の書き込み操作を実行してはいけません。

トラブルシューティングと制約

• モデルがJSONの前後に文章を返す： 厳密に解析し、失敗した場合はエラー経路に送ります。エンドポイントが対応していれば構造化出力を要求できますが、対応していると決めつけずに確認してください。
• テストの実行がまだ終わっていない： 完了を待つか、保留ステータスで停止します。「まだ失敗が報告されていない」ことを成功と解釈してはいけません。
• 承認後に新しいコミットが追加された： 承認されたリビジョンと現在のヘッドを比較し、異なる場合はチェックを再実行して承認を取り直します。
• diffに機密ファイルまたは生成ファイルが含まれる： モデルに内容を送る前に除外するか、プルリクエストを人に回します。
• レビュアーが承認対象を判断できない： 対象リポジトリ、リビジョン、提案された操作、テストの根拠をリクエストに含め、操作パラメーターを確認できる状態にします。

簡潔なデプロイ前チェックリスト

書き込み操作を有効にする前に、ワークフローが無効なスキーマを拒否すること、再試行回数に上限があること、失敗または保留中のテストで停止すること、リビジョンの変更に対処できること、拒否が書き込みを行わない経路に送られることを確認してください。サンプルデータと本番以外のリポジトリを使って、各エラー分岐をテストします。まずはすべてのマージに承認を必須とし、明確で文書化された根拠をチームで用意できてから、そのポリシーを変更してください。

信頼性を高める基本はシンプルです。抽出範囲を絞り、機械的に検証し、正確なリビジョンに対して確認を行い、影響の大きいリポジトリ操作は人が承認します。n8nの承認ステップは処理を一時停止するために役立ちますが、スキーマ検証、再試行ルール、リビジョン保護はワークフロー側にも必要です。

参考資料

• n8n：ツールのhuman-in-the-loop — 承認の動作、対応するレビューチャネルの例、ツールパラメーター、システムプロンプトに関するガイダンス。