GitHub のプルリクエストが出るたびに、差分を社内のコーディング規約とセキュリティの観点で一次レビューし、指摘をコメントの下書きにする

処理の起点を決める

n8n の GitHub Trigger で、対象のリポジトリの Pull request のイベントを受け取ります。 GitHub から n8n へ webhook が届く形なので、n8n は GitHub から HTTPS で届く場所に置きます。 社内に置く場合は、webhook の受け口だけを外から届くようにします。

受け取った直後に If ノードで外すものを決めます。

synchronize（新しいコミットの追加）でも動かしますが、見るのは前回からの差分だけにしたい場面があります。 最初の版では、更新のたびにプルリクエスト全体の差分を見直し、前回と同じ指摘は Data Table と照らして出さないようにします。毎回同じ指摘が Slack に届くと、レビュー担当者は下書きを読まなくなります。

入力データを集める

質を決めるのは、規約の文書の書き方です。 「適切に例外を扱う」としか書かれていない項目は、AIにも人にも当て方が分かりません。わるい例とよい例が書いてある項目ほど、指摘が当たります。 規約の文書を直すことが、そのままこの構成の精度になります。

規約は毎回リポジトリから取ります。 規約を更新したら、次のプルリクエストからその版で見ることになり、どの版の規約で指摘したかを記録に残せます。

データの取得方法を決める

変更ファイルの一覧は、GitHub の REST API の「List pull requests files」で取ります。 公式ページでは、応答に含まれるファイルは最大3000件で、既定では1ページに30件とされています。30件を超えるプルリクエストもあるので、ページをたどって全件を取ります。 n8n では、GitHub ノードに無い操作を HTTP Request ノードで GitHub の資格情報を使って呼ぶことができます。

n8n の GitHub ノードには、Pull Request の Get Diff・Get Patch、Review の Create などの操作があります。 ただし、行にひも付けたコメントを含むレビューを細かく組み立てるために、投稿は HTTP Request で REST API を直接呼びます。

AIへ渡す前に整形する

1. 対象外のファイルを外す … 生成物、ロックファイル、画像、テストの固定データは渡しません
2. 差分が大きすぎるものを分ける … 変更の行数が決めた上限を超えるプルリクエストは、AIに渡さず「大きすぎて一次レビューの対象外」としてレビュー担当者に知らせます
3. 差分の行に番号を振る … ファイルごとに、追加された行に L1、L2 のような番号を振ります。AIはこの番号で場所を返します
4. 番号と差分の位置の対応表を作る … 各番号が、そのファイルの差分の中で何行目にあたるかを持っておきます
5. 秘密情報らしい文字列を確かめる … アクセスキーや接続文字列に見える文字列が差分にあれば、AIに渡す前に伏せ、そのこと自体をレビュー担当者に知らせます
6. 規約の文書から項目を取り出す … 項目番号と本文の組にしてAIに渡します

4番目が、この構成の要です。 GitHub の公式ページでは、レビューのコメントの position は差分の中の位置で、ファイルの行番号とは違うとされ、ファイルの最初の @@ の行の次が1、その後は空白の行や次のまとまりをまたいでも増え続けるとされています。この数え方をAIに任せず、Code ノードで機械的に変換します。

5番目は、見つけたこと自体が指摘になります。 差分に認証情報が入っていれば、AIのレビューより先に、そのコミットの扱いをレビュー担当者が決める必要があります。

AIに処理させる

Basic LLM Chain に、差分を規約とチェック項目に照らした校正をさせます。 公式ページでは、Basic LLM Chain はプロンプトを決め、出力の形を求めるときは Structured Output Parser などをつなぐとされています。

「確からしさ」を持たせるのは、差分だけでは分からないことが多いからです。 入力の検証は、呼び出し元で済んでいるかもしれません。差分の外を見ないと言い切れないものは、needs_context として分け、言い切りの指摘と混ぜません。

指示内容を固定する

Basic LLM Chain のシステムメッセージに、次のように書きます。

あなたは社内の開発チームのレビュー担当者として、プルリクエストの差分を
社内のコーディング規約とセキュリティのチェック項目に照らして一次レビューします。

【入力】
- 規約の項目（項目番号、本文、よい例・わるい例）
- セキュリティのチェック項目（項目番号、見るべきこと）
- 変更ファイルごとの差分。追加された行には L1, L2 ... の番号が振ってあります

【進め方】
1. 追加された行（番号の付いた行）だけを対象にしてください。
   削除された行と、変更の無い行には指摘しないでください。
2. 各行について、規約とチェック項目のどれかに反しうるかを見てください。
3. 指摘ごとに、ファイル名、行の番号、項目番号、指摘の文を書いてください。

【厳守事項】
- 項目番号を示せない指摘は出さないでください。好みや一般論での指摘は不要です。
- 指摘の文には、項目の本文に書かれた直し方だけを添えてください。
  修正したコードの全文は書かないでください。
- 差分の外のコードを見ないと言い切れないもの（呼び出し元で検証済みかもしれない等）は
  confidence を "needs_context" にしてください。"certain" にしないでください。
- 行の番号は、差分に振られた L の番号をそのまま返してください。
  ファイルの行番号や差分の位置を自分で数えないでください。
- 伏せ字（[MASKED]）の中身を推測しないでください。
- 設計の良し悪し、仕様との一致、マージしてよいかは書かないでください。
- 指摘が無ければ、findings を空にしてください。無理に指摘を作らないでください。

「項目番号を示せない指摘は出さない」が最も大事な一文です。 書いておかないと、AIは変数名の好みやコメントの書き方のような、規約に無い一般論を指摘に混ぜます。 一般論が混ざると、レビュー担当者は全部を自分の判断で仕分け直すことになります。

「指摘が無ければ空にする」も効きます。 書いておかないと、問題の無い差分にも「念のため」の指摘を作ります。空の結果が返ることを正常として扱います。

出力形式を固定する

Structured Output Parser で、次の形に決めます。 公式ページでは、JSON の例から生成するか、JSON Schema で定義するかを選べ、例から生成するとすべての項目が必須として扱われるとされています。

{
  "pull_number": 1234,
  "rules_version": "",
  "findings": [
    {
      "file": "src/api/orders.ts",
      "line_ref": "L12",
      "rule_id": "SEC-07",
      "category": "coding_rule | security",
      "confidence": "certain | needs_context",
      "comment": ""
    }
  ],
  "skipped_files": [],
  "summary": ""
}

1つ目の理由は、rule_id を必須にできることです。 規約の項目一覧に無い番号が返ってきたら、ワークフローがその指摘を外します。 項目番号の無い指摘は、出力の形の段階で通りません。

2つ目は、line_ref を位置に変える処理を分けられることです。 ワークフローは前処理で作った対応表で L12 を差分の位置に変えます。対応表に無い番号が返ってきたら、その指摘は外して記録します。

3つ目は、confidence で投稿の書き方を変えられることです。 needs_context の指摘は、コメントの冒頭に「差分の外で対応済みなら不要です」と添えて投稿します。

Slack の下書きは、次の形で送ります。

システムへ連携する

レビュー担当者への提示には、Slack ノードの Send and Wait for Response を承認の形で使います。 n8n の公式ページでは、この操作で承認する人が Slack の中で承認・却下でき、ブラウザのページは開かず、誰が応じたかが出力に記録されるとされています。承認できる人を指定でき、指定外の人には個別の案内が出てワークフローは待ち続けます。承認できる人を、プルリクエストで指定されたレビュー担当者にします。

この形には条件があります。 公式ページでは、Slack の中で承認するには、n8n が Slack から公開の HTTPS で届く場所にあること、Slack のアプリで Interactivity を有効にして n8n の受け口を登録すること、資格情報に Slack のアプリの Signing Secret を入れることが要るとされています。Signing Secret が無いと、ボタンは出ても押してもワークフローが再開しません。

投稿は、REST API の「Create a review for a pull request」で行います。 公式ページでは、event に APPROVE・REQUEST_CHANGES・COMMENT を選べ、comments にファイルのパス・差分の位置・本文を並べて行にコメントを付けられます。この構成は COMMENT だけを使い、APPROVE と REQUEST_CHANGES は使いません。 commit_id には受け取った最新のコミットを入れます。公式ページでは、最新でないコミットを指定すると、後のコミットがその位置を変えたときにコメントが古くなるとされています。

保留中のレビューは使いません。 公式ページでは、event を空にすると保留中（PENDING）のレビューになり、GitHub の説明では、保留中のコメントは提出するまで本人にしか見えないとされています。機械用のアカウントで作った保留中のレビューは、レビュー担当者には見えません。

人が確認する

指定されたレビュー担当者が、Slack の下書きを見て投稿するかを選びます。

1. 伏せ字の知らせを先に見る … 認証情報らしい文字列があったなら、指摘の投稿より先に、そのコミットの扱いを決めます
2. certain の指摘を確かめる … 項目番号と指摘の文が、差分の行に当たっているかを見ます
3. needs_context の指摘を確かめる … 呼び出し元などを見て、要るかどうかを決めます
4. 投稿するかを選ぶ … 外れた指摘が混ざっているときは「投稿しない」を選び、要る指摘だけを自分で書きます

4番目の選び方を、チームで決めておいてください。 一部だけ外れている下書きを「投稿する」で流すと、外れた指摘に開発者が答える時間が生まれます。 最初の数か月は、外れが1つでもあれば「投稿しない」とし、記録を見て規約とプロンプトを直します。

目標は、下書きの確認を1件ならして4分に収めることです。 差分を読み直すのではなく、項目番号が当たっているかを見る作業にします。

例外に対処する

2行目は気づかないまま起きます。 一覧は既定で1ページ30件なので、ページをたどる処理を入れ忘れると、大きなプルリクエストの後半のファイルが、一次レビューを通ったように見えます。

記録を残す

• プルリクエストの番号、最新のコミット、使った規約の版
• AIに渡したファイルと、外したファイル・伏せ字にした箇所
• AIの出力（指摘、項目番号、確からしさ）と、外した指摘とその理由
• レビュー担当者の選択（投稿する／投稿しない）と、応じた人と時刻
• 投稿したレビューのID
• 項目番号ごとの、投稿された数と「投稿しない」になった数

4つ目と最後の行を残すのは、規約とプロンプトを直すためです。 ある項目の指摘がいつも「投稿しない」になるなら、その項目の本文が曖昧か、AIの当て方がずれています。 項目ごとに数えると、直す場所が分かります。