人による承認とテスト検証を備えたn8nのコード変更ワークフローを構築する

ワークフローの概要

n8nでAIエージェントにリポジトリへの変更を提案させ、書き込み操作には人による承認を必須にします。承認された書き込みの後、生成された正確なコミットに対してテストを実行し、結果を報告します。マージやデプロイは別の判断として扱います。

重要なのは、ツールの承認と出力の承認の違いです。n8nでは、人によるレビューステップを使って、選択したツールの実行前にAI Agentを一時停止できます。レビュアーには提案されたツールとそのパラメータが表示されます。承認するとその呼び出しが実行され、拒否するとキャンセルされてエージェントに通知されます。この動作はn8nのヒューマンインザループガイドに記載されています。

OneMuxは、1つのOpenAI互換APIを通じてAIモデルへのアクセスを提供します。この設計でモデルにアクセスする方法の候補ですが、n8nとの連携が検証されているわけではありません。OneMux APIドキュメントとn8nノードの設定を確認し、使用予定のエンドポイントとパラメータに対応しているか確かめてください。

構築前に必要なもの

• AI Agent、適切なチャットモデル接続、Slackやn8n Chatなどの人によるレビューチャネルへのアクセスを備えたn8nインスタンス。
• 指定されたリビジョンを読み取り、本番環境以外のブランチにパッチを適用できるリポジトリ連携またはカスタムサービス。その書き込み用認証情報には、対象のリポジトリとブランチに必要なアクセス権のみを付与します。
• 本番環境の認証情報やシステムから分離されたテストランナー。正確なコミット識別子を受け取り、ステータスと結果へのリンクまたは参照を返せる必要があります。
• モデル呼び出しにOneMuxを選ぶ場合は、OneMuxアカウントとAPIアクセス。最新の接続情報はクイックスタートを、利用可能なモデルの選択にはモデルカタログを確認してください。
• テストコマンドが明確で、デフォルトブランチが保護され、提案された変更をレビューする権限を持つ担当者がいるリポジトリ。

これは実装パターンであり、インポート可能なワークフローではありません。リポジトリツール、ランナー連携、モデルの選択、n8nの具体的なフィールドは環境によって異なります。特に、提供されたドキュメントからは、特定のOneMuxモデルがn8n AI Agentに必要なツール呼び出し動作をサポートしていることは確認できません。この設計を採用する前に対応状況を確認してください。

正確なリビジョンを中心にワークフローを設計する

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

1. リクエストを受け付ける。 信頼できるワークフロー設定から、リポジトリ、課題の説明、作業対象ブランチ、ベースコミット、許可されたテストコマンドを取得します。
2. 読み取って提案する。 エージェントにベースコミットの関連ファイルを確認させ、パッチを作成させます。読み取り用アクセスではリポジトリを変更できないようにします。
3. 書き込みをレビューする。 パッチ適用ツールをn8nの人によるレビューに通します。レビュアーは提案されたツール呼び出しを承認または拒否します。
4. 適用してコミットを特定する。 承認された場合、書き込みサービスはブランチが承認済みのベースコミットを引き続き指していることを確認し、承認されたパッチを適用して新しいコミットIDを返します。ベースが変わっていた場合は処理を拒否し、新たな提案と承認を求めます。
5. 検証する。 分離されたランナーで、その正確な新しいコミットに対して設定済みのテストを実行します。コマンド、コミット、ステータス、結果の参照先を記録します。
6. 報告する。 レビュアーと依頼者にコミットとテスト結果を送ります。テストが失敗、中止、または結果なしの場合は合格ではありません。

これらは推奨される管理策であり、n8nの人によるレビューステップが保証する機能ではありません。特に、ベースコミットの確認を強制し、承認されたパッチと実際に適用するパッチが同一であることを保証する必要があるのは、リポジトリサービスです。

モデル接続を設定する

n8nで、OpenAI互換エンドポイントを設定でき、かつAI Agentに必要なツール呼び出し動作をサポートするチャットモデル設定を選びます。エンドポイント、認証方法、モデル識別子は、最新のOneMuxドキュメントに記載されたものを使用してください。認証情報はプロンプトやワークフローメッセージではなく、n8nの認証情報管理機能に保存します。

リポジトリへのアクセスを接続する前に、小さなテストリクエストを送り、n8nノードが期待する形式でレスポンスが返ることを確認します。次に、影響のないツール呼び出しをテストします。OpenAI互換だからといって、すべてのエンドポイント、パラメータ、ツール呼び出し形式を相互に置き換えられるわけではありません。ここでの互換性は、必要なリクエストとレスポンスを双方がサポートしていることが条件です。この設定は、この記事のためにテストされていません。

利用可能なモデル接続がエージェントのツール呼び出しに対応できない場合でも、モデルに直接書き込み用認証情報を与えて承認を回避してはいけません。互換性のある設定を使うか、書き込みサービスへの引き渡しを別途構築し、明示的なレビューを設けてください。

リポジトリへの書き込みに人による承認を追加する

AI AgentノードでToolsコネクタを開き、Tools PanelのHuman reviewを探します。承認チャネルを選択し、その認証情報を設定します。リポジトリに書き込むツールを、レビューステップのツールコネクタに接続します。必要に応じて読み取り専用ツールは分離し、外部の状態を変更できる他のツールにも、それぞれレビューまたは同等の管理策を設けます。

n8nのドキュメントによると、レビュアーはツール名とAIが指定したパラメータを受け取れます。たとえば、レビューメッセージを次のように設定します。

Proposed tool: {{ $tool.name }}
Proposed parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

レビュー可能な入力に、リポジトリ、ブランチ、ベースコミット、完全なパッチ、またはダイジェスト付きの変更不可能なパッチ参照が含まれる書き込みツールを使用します。パッチがチャネルに対して大きすぎる場合は、安全にアクセスできるレビュー先を用意し、書き込みサービスが同じ内容を適用することを確認します。「テストを修正する」といった曖昧な指示だけでは、特定のリポジトリ変更を承認するには不十分です。

ドキュメントに記載された$tool.parametersの値には、$fromAI()式で設定されたフィールドが含まれます。すべての固定された認証情報、非表示の設定値、後続の影響がメッセージに表示されると決めつけてはいけません。固定設定を制限し、レビュアーが別の方法で確認できるようにします。パラメータは承認メッセージに表示される可能性があるため、ツールのパラメータに秘密情報を含めないでください。

承認対象のツール名と、拒否された場合のエージェントの対応を記したシステム指示を追加します。たとえば、次のようにします。

Repository writes require human approval. Propose a patch against the
specified base commit and request the write tool only for that patch.
If approval is denied, do not retry the write or use another tool to make
the change. Tell the requester it was denied and ask for clarification.
Report test results only when supplied by the test runner.

この指示はエージェントによるレビュー対応を助けますが、セキュリティ境界ではありません。権限とブランチの制限はプロンプトの外で強制してください。

承認された変更を検証する

テストランナーは、書き込みサービスがコミットIDを返した後にのみ起動します。ランナーがブランチの最新の先頭ではなく、そのIDをチェックアウトし、チームが定義した許可リスト上のコマンドを実行するよう設定します。リポジトリのメンテナーが選択している場合、コマンドの例は次のようになります。

npm test

このコマンドはあくまで例です。プロジェクトの実際のテスト手順を使用してください。リポジトリのコード、依存関係のインストールスクリプト、テスト出力は信頼できないものとして扱います。ネットワークとファイルシステムへのアクセスを制限し、本番環境の秘密情報を与えず、時間とリソースに上限を設けて実行します。テストスイートの合格が示すのは、選択されたチェックがその環境で合格したことだけであり、変更の安全性や正しさを証明するものではありません。

承認されたベース、新しいコミット、テストコマンド、合否ステータス、ログへのリンクを含む簡潔な結果を返します。テストが失敗した場合、エージェントは修正パッチを提案できますが、追加の書き込みには改めて承認が必要です。レビュアーが先のツール呼び出しを承認したからといって、自動的にマージしてはいけません。

トラブルシューティングと運用上の制限

承認リクエストに必要な情報がない

どの入力がAIから提供され、$tool.parametersで確認できるかを調べます。パッチを特定する情報、ブランチ、ベースリビジョンをレビュー可能なツール入力に含めるか、安全で変更不可能なレビュー用成果物を提供します。レビュアーが正確な書き込み内容を特定できない場合は、拒否します。

エージェントがツールを呼び出せない

まず、リポジトリの権限とは切り離して、影響のないツールをテストします。n8nノード、OneMuxエンドポイント、選択したモデル、必要なツール呼び出しパラメータについて、それぞれの最新ドキュメントを確認します。提供された情報源では、特定のモデルとノードの組み合わせは検証されていません。

ブランチが進んだ、またはテストが完了しなかった

古くなった書き込みは、別のベースにパッチを適用するのではなく拒否します。タイムアウト、ランナーエラー、ログの欠落があった場合は、検証が未完了であると報告します。適切な場合は同じコミットに対して再実行し、提案された書き込みが変わる場合は新たな承認を求めます。

まとめ

重要なのは、承認の範囲を限定することです。人が特定のリポジトリへの書き込みを承認し、分離されたランナーが生成されたコミットを検証します。n8nはドキュメントに記載されたツール単位の一時停止と承認フローを提供し、残りの安全策はリポジトリサービス、ランナー、権限、レビュープロセスで担保します。OneMuxをモデルアクセス層として使用するのは、選択したエンドポイントとパラメータがn8nの設定で動作することを確認してからにしてください。

参考資料

• n8n: Human-in-the-loop for tools — ツール承認の動作、設定、レビューチャネル、レビューメッセージの変数。
• OneMux documentation — 最新のAPI接続情報を確認できます。