自社製品の GitHub に届く Issue を読み、不具合・要望・質問と影響する部品で分けてラベルと担当の候補を付け、似た既存の Issue を重複の候補として示す

処理の起点を決める

GitHub のリポジトリの webhook で、Issues のイベントを n8n の Webhook ノードに送ります。 GitHub の公式ページでは、issues のイベントの action に opened・edited・reopened・labeled・closed・transferred・typed などがあります。この構成で動かすのは opened と reopened だけで、それ以外は受け取った直後に外します。

受け取ったら、まず署名を確かめます。 GitHub の公式ページでは、X-Hub-Signature-256 のヘッダーに、webhook の秘密の値を鍵にして受け取った本文そのものから作った HMAC-SHA256 の値が入り、こちらで同じ計算をして一定の時間で比べる関数で照合し、単純な == で比べないように、とされています。n8n の Webhook ノードは、オプションの Raw Body で加工前の本文を受け取れます。加工後の JSON から計算し直すと、値が合いません。

応答はすぐ返します。 GitHub の公式ページでは、届いてから10秒以内に2XXで応答し、時間がかかる処理は後ろの待ち行列で行うよう勧めています。Webhook ノードの応答を Immediately にし、検索とAIの判定は応答の後で行います。

X-GitHub-Delivery のヘッダーで、同じ配送を二度処理しないようにします。 公式ページでは、この値は配送ごとに一意で、配送をやり直しても元と同じ値とされています。Data Table に記録した値と照らします。

入力データを集める

質を決めるのは、部品の対応表の「説明」です。 「Webhook の署名検証：加盟店のサーバーで受け取る Webhook の署名を検証するライブラリ。決済の通知を受け取れない、署名が合わない、という報告はここ」。利用者が書く言葉で説明しておくと、部品の判定が当たります。

テンプレートの欄は、見出しで区切って本文に入ります。 欄が空のままの Issue は、見出しの下が空か「_No response_」のような文言になります。ワークフローが欄ごとに切り出し、空の欄を「足りない情報」の手がかりにします。

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

似た Issue は、GitHub の検索 API で集めます。 公式ページでは、/search/issues に search_type を指定でき、semantic は埋め込みによる意味の検索、hybrid は意味の検索と語の検索を組み合わせたものとされています。題名と本文の冒頭を検索の語にし、repo: と is:issue で対象のリポジトリの Issue に絞ります。

検索 API には回数と長さの上限があります。 公式ページでは、検索 API は認証して1分に30回、semantic と hybrid は認証が必須で1分に10回とされています。検索の語は256文字まで（演算子と修飾子を除く）で、AND・OR・NOT は5つまでとされています。題名と本文の冒頭を、256文字に収まるように切ります。

意味の検索が日本語の Issue でどこまで効くかは、公開ページからは分かりません。 最初に過去の重複の組で確かめ、hybrid で拾えない組が多ければ、語の検索（既定）と並べて候補を集めます。

AIへ渡す前に整形する

1. 対象の絞り込み … action が opened・reopened 以外、作成者がボット、対象外のリポジトリを外します
2. テンプレートの欄の切り出し … 見出しごとに値を取り、空の欄を記録します
3. 伏せ字 … アクセスキー、API キー、トークン、接続文字列らしい文字列を [MASKED] に置き換えます
4. 検索の語の作成 … 題名と本文の冒頭から、記号とコードの断片を除き、256文字以内にします
5. 候補の整形 … 検索結果の10件を、番号・題名・状態・本文の冒頭400文字・ラベルにそろえます
6. 自分自身を外す … 検索結果に、いま立った Issue 自身が入っていれば外します

3番目は、利用者が設定ファイルやログを貼るためです。 決済の SDK の Issue には、テスト用ではない API キーが貼られることがあります。 伏せたうえで、見つけたこと自体を当番に知らせます。 キーの失効を利用者に勧めるのは、当番が判断します。

6番目を忘れると、AIが「この Issue 自身と重複」と判定します。 立った直後の Issue が検索に出るかは時間によるので、番号で必ず外します。

AIに処理させる

Basic LLM Chain に、Issue の区分と重複の候補の判定をさせます。 公式ページでは、Basic LLM Chain はプロンプトを決めるノードで、出力の形を求めるときは Structured Output Parser などのパーサーをつなぐとされています。

「影響の広さの手がかり」は、決めるのではなく、書かれていることを拾うだけにします。 「iOS 17 の一部の端末で」と書かれていれば特定の環境、「全加盟店で決済が通らない」と書かれていれば全員。書かれていなければ「不明」です。 優先順位はこの手がかりを見て人が決めます。

指示内容を固定する

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

あなたは決済SDKの開発チームで、新しい Issue を受け付ける当番を補助します。

【入力】
- 新しい Issue（番号、題名、本文、テンプレートの欄と空の欄）
- 部品の一覧（部品ID、部品名、説明）
- 種類ごとの必須の情報の一覧
- GitHub の検索で集めた似た Issue の候補（最大10件。番号、題名、状態、本文の冒頭）

【判定すること】
1. type: bug / feature / question のどれか。
   不具合の報告を含むなら、要望や質問が混ざっていても bug を選んでください。
2. components: 部品IDを1つ、関係が明らかなら2つまで。分からなければ ["unknown"]。
3. scope_hint: 本文に書かれた影響の範囲を写してください。書かれていなければ "不明"。
4. missing_info: 必須の情報のうち、本文から読み取れないものの名前。
5. duplicates: 候補のなかから、同じ不具合・同じ要望と言えるものを選び、
   番号、"same" か "related"、理由を1文で書いてください。
6. security_concern: 認証・署名・権限の回避など、公開の場で詳しく扱うべきでない
   報告なら true にしてください。

【厳守事項】
- duplicates に入れてよいのは、候補の一覧にある番号だけです。
  候補にない番号を挙げないでください。
- 同じ部品の Issue というだけで same にしないでください。
  症状と条件がそろって同じと言えるときだけ same にしてください。
- 担当者、優先順位、重大度、原因、直し方は書かないでください。
- [MASKED] の中身を推測しないでください。
- missing_info は、本文のどこにも書かれていないものだけにしてください。
  テンプレートの欄が空でも、本文の別の場所に書かれていれば足りています。

「候補の一覧にある番号だけ」が最も大事な一文です。 書いておかないと、AIは「#1024 と似ています」のように、候補に無い番号を作って挙げることがあります。ワークフローでも、候補に無い番号は捨てます。

「欄が空でも、本文の別の場所に書かれていれば足りている」も効きます。 利用者は版をテンプレートの欄ではなく本文の冒頭に書くことがあります。欄だけを見て聞き返すと、書いたのに読まれていないと受け取られます。

出力形式を固定する

Structured Output Parser で、次の形に決めます。 公式ページでは、JSON の例から生成するとすべての項目が必須として扱われ、JSON Schema で定義することもでき、$ref を使った参照には対応しないとされています。

{
  "issue_number": 2481,
  "type": "bug | feature | question",
  "components": ["webhook-signature"],
  "scope_hint": "",
  "missing_info": ["sdk_version", "repro_steps"],
  "duplicates": [
    { "number": 2310, "relation": "same | related", "reason": "" }
  ],
  "security_concern": false
}

1つ目の理由は、ワークフローが中身を検査できることです。 components が対応表に無い部品IDなら unknown に直し、duplicates の番号が候補に無ければ捨てます。検査を通ったものだけが当番への案になります。

2つ目は、ラベルと担当を規則で決められることです。 種類のラベルは type から、部品のラベルと担当は components から対応表で引きます。部品が2つなら担当の候補も2人になり、当番がどちらかを選びます。

3つ目は、security_concern で流れを分けられることです。 true なら、ラベルの案も聞き返しの下書きも作らず、セキュリティの担当の Slack に直接知らせます。 公開の Issue への書き込みは、セキュリティの担当が決めます。

当番に送る案は、次の形にします。

システムへ連携する

ラベルと担当は、REST API の「Update an issue」で付けます。 公式ページでは、labels と assignees は渡した値で今の設定を置き換え、空の配列を渡すと消えるとされています。今付いているラベルを取ってから足し合わせて渡します。 足し合わせずに渡すと、利用者や他の開発者が付けたラベルが消えます。

機械用のアカウントには、トリアージの権限を持たせます。 公式ページでは、Issue を編集できるのは作成者と、書き込みの権限かトリアージの役割を持つ人で、書き込みの権限が無いとラベルと担当の変更は黙って捨てられるとされています。反映の後に Issue を取り直し、ラベルが付いたかを確かめます。

重複の印は、コメントで付けます。 GitHub の公式ページでは、新しいコメントの本文に「Duplicate of #番号」と書くと「重複として印が付いた」というタイムラインの出来事が加わり、コメントする人にはそのリポジトリへの書き込みの権限が要るとされています。この印は閉じることとは別で、閉じるのは当番が行います。

当番への確認には、Slack の Send and Wait for Response を承認の形で使います。 公式ページでは、Slack の中で承認・却下でき、承認できる人を指定でき、誰が応じたかが出力に残るとされています。承認できる人を、その週の当番に限ります。 n8n が Slack から公開の HTTPS で届くこと、Interactivity の受け口、Signing Secret が要ります。

人が確認する

その週の当番が、Slack の案を確かめます。

1. 伏せ字と脆弱性の知らせを先に見る … キーが貼られていたら、ラベルより先に利用者への連絡を決めます
2. 重複の候補を見る … same の候補を開き、症状と条件が同じかを見ます
3. 部品と担当を見る … 部品が2つのときは、どちらの担当にするかを選びます
4. 聞き返しの下書きを読む … 足りない情報が本当に書かれていないかを本文で確かめます
5. 反映するかを選ぶ … 外れがあれば「反映しない」を選び、自分で付けます

2番目で重複と認めても、すぐには閉じません。 「Duplicate of #番号」のコメントで利用者に元の Issue を示し、利用者が「違う」と返せる時間を置いてから閉じます。 自動で閉じると、別の不具合を見落とします。

目標は、1件をならして3分です。 案が当たっていれば1分で終わり、重複の候補を読み比べるものは数分かかります。

例外に対処する

最後の行は、GitHub が自動ではやり直さないためです。 公式ページは、サーバーが戻ったら届かなかった配送をやり直すよう勧めています。止まっていた間に立った Issue は、案が作られないまま残ります。

記録を残す

• 配送のID、Issue の番号、受け取った日時、外した理由
• 伏せ字にした箇所の種類（中身は残さない）
• 検索の語と、候補の10件の番号
• AIの判定（種類、部品、足りない情報、重複の候補、脆弱性の疑い）と、検査で直した箇所
• 当番の選択と、応じた人と時刻、当番が直したラベルと担当
• 反映したラベル・担当・コメントのID

当番が直したラベルと担当を残すのは、対応表の説明を直すためです。 ある部品がいつも別の部品に直されるなら、説明の言葉が利用者の書き方と合っていません。