GitHub App の @-mention が初回は auto-link されない仕様
まとめ
- GitHub App の bot user (
<slug>[bot]) を@<slug>で mention しても、bot がその repo の participant になるまで auto-link されず plain text のまま表示される - bot が participant になる条件は「その repo で 1 度でもコメント済み」「assignee」「同 thread の他参加者」のいずれか
- bot 機能を作るなら mention の auto-link / autocomplete に依存せず本文 grep でメンション検出する 設計にすべき
- 初回 mention のたびに「反応しない bot」と誤認されるのを避けるため、最初の質問→応答のループまで含めて検証してから運用に出す
起きた現象
GitHub App を作成して repo にインストール、bot user @<slug> 宛てに @<slug> 質問 というコメントを issue に投稿。期待動作は:
- ✅ コメント本文の
@<slug>がハイパーリンク化される（autocomplete 候補にも出る） - ✅ bot が mention 通知を受けて応答する
実際:
- ❌
@<slug>は plain text のまま、リンク化されない - ✅ ただし bot 側で本文 grep していたので、応答自体は正常に投稿された
「リンク化されない」状態は GitHub UI 上で違和感がある（mention のつもりが普通の文字列）。
原因: GitHub の autocomplete / auto-link が participant 限定
GitHub の @ mention 関連の UI 補助は 「その repo の participant にあたるユーザ」 にしか効かない。具体的に participant とみなされる条件:
| 条件 | 例 |
|---|---|
| その repo で 1 度でもコメント済み | bot が過去に 1 件でも comment を投稿していれば OK |
| assignee | issue / PR にアサインされている |
| 同 thread の他参加者 | 既に参加している thread で mention するなら OK |
| collaborator / contributor | 通常の repo 権限を持つ |
新規 thread の 初回 mention はこれらをどれも満たさない。GitHub から見ると「あなたが書いた @<slug> は、この repo にとっては未知のユーザを指している」状態なので、リンク化も autocomplete も発動しない。実在する bot user を正しく参照していても挙動は同じ。
仕様の確認ポイント
bot のコメントを 1 件入れた後で同じ thread に再度 @<slug> を書くと、今度は auto-link される。これは GitHub が「bot は participant」と認識した証拠。autocomplete 候補にも出てくるようになる。
ただしキャッシュ反映に数分〜数時間かかるケースがあり、直後の再投稿でも auto-link しない ことがある。これは GitHub 側の挙動なので待つしかない。
設計への含意: 本文 grep が必須
bot 機能を作る側の正しい設計:
- mention の auto-link 有無に依存しない
- コメント本文の文字列マッチで
@<slug>を検出する /repos/{O}/{R}/issues/{N}/comments?since=で diff polling、本文 grep でフィルタ
この設計なら plain text のままでも検出できるので、初回 mention でも問題なく反応する。GitHub の Notifications API (/notifications?participating=true) で取ろうとすると、participant 化していない初回の mention を取り逃すリスクがあるので推奨できない。
正規表現の注意点:
@<slug>-fooのような誤マッチを避けるため word boundary を使う[bot]サフィックスはユーザが本文に書かないので、grep 対象は@<slug>のみ[bot]は author.login の判定（自分のコメントを除外する用途）でだけ使う
補足: 自己除外の判定
bot が自分自身のコメントに反応すると無限ループになる。除外には 2 通りの判定軸がある:
author.loginの末尾が[bot]かauthor.type == "Bot"か
bot 名を hardcode で書くと改名時に壊れるので、[bot] サフィックスや author.type で汎化 するのが安全。
ユーザ体験的な落としどころ
- 初回 mention: plain text のまま見えるが bot は反応する
- 2 回目以降: GitHub が学習して auto-link、autocomplete も効く
- 仕様上の問題はなし、最初に「あれ、リンクにならない」と思わせるだけ
これを知らずに bot を運用に出すと、ユーザが「メンションが効いていないのでは」と誤認してトリガーを書き直したりする。ドキュメントに「初回は plain text でも問題ありません」と書いておくと混乱を避けられる。