Thread Owl

AI 支援による Pull Request レビューのための GitHub App バックエンド。

概要

Thread Owl は、AI 支援 PR ワークフローにおける Bot アイデンティティ・installation token 管理・リポジトリ allowlist・Webhook エントリポイント・レビュースレッド操作を提供する。

主目的は、PR レビュー操作（コメント投稿・スレッド返信・summary）の実行主体を個人 GitHub アカウントから GitHub App installation に移行し、organization メンバーまたはリポジトリ collaborator としてのレビュー専用アカウントを不要にすることである。

設計方針

• GitHub App を投稿主体にする — レビュー操作はすべて installation token を使って実行する。個人アクセストークンに依存しない
• resolve は修正側に委ねる — Thread Owl はレビュアー側として指摘と返信を投稿し、スレッドの resolve は PR author または repository write access を持つ修正側が行う
• LLM を内蔵しない — Thread Owl は LLM を持たない。ChatGPT・Claude・Codex などの認証・投稿レイヤーとして機能する
• 半自動化から始める — 完全自動化は opt-in で後続フェーズに委ねる。初期は人間承認付きレビュー操作の安定化を優先する

アーキテクチャ

LLM フロントエンド（ChatGPT / Claude / Codex）
        ↓ MCP tools（stdio / Streamable HTTP）/ internal API
Thread Owl
  ├─ GitHub App Auth（JWT → installation token → キャッシュ）
  ├─ Repository Policy（allowlist・per-repo config）
  ├─ Review Operations（PR 取得・スレッド一覧・コメント投稿・返信）
  ├─ Webhook Receiver（署名検証・重複排除・イベント正規化・キュー投入）
  ├─ MCP Server（tools + subscriptions）
  └─ Internal API（health・token-source・status）
        ↓ GitHub REST / GraphQL API
GitHub

ロードマップ

フェーズ	内容
0	リポジトリ初期化（完了）
1	GitHub App 認証 MVP
2	レビュー操作 MVP
3	MCP 統合
4	MCP Streamable HTTP / mcp-gateway 連携
5	Webhook 受信
6	subscribe 通知
7	制御付き自動化
8	API LLM ワーカー（opt-in）

詳細は docs/roadmap.md を参照。

動作要件

• Node.js >= 20.0.0
• pnpm

セットアップ

pnpm install
cp .env.example .env
# .env に GitHub App の認証情報を記入する

GitHub App の登録手順は docs/github-app-setup.md を参照。

開発コマンド

pnpm run check      # Biome lint + フォーマット確認
pnpm run typecheck  # TypeScript 型チェック
pnpm test           # テスト実行
pnpm run build      # dist/ へコンパイル

Docker イメージ

ghcr.io/scottlz0310/thread-owl として公開している。タグ運用は姉妹リポジトリ（mcp-gateway / review-raven）と同じモデルに揃えている。

タグ	内容	発行タイミング
:latest	安定リリース（最新の vX.Y.Z と同一）	git tag vX.Y.Z push 時
:X.Y.Z / :X.Y	特定バージョンの固定参照	git tag vX.Y.Z push 時
:main	開発ビルド（main 追従）	main への push ごと

# 安定版（推奨）
docker pull ghcr.io/scottlz0310/thread-owl:latest

# 開発版（bleeding-edge）
docker pull ghcr.io/scottlz0310/thread-owl:main

リリース手順

v プレフィックス付きの semver タグを push すると、release.yml がテスト・イメージ発行（:latest + version タグ）・GitHub Release 作成まで行う。

タグを push する前に package.json と src/index.ts の VERSION を揃える。 release.yml はタグ・package.json・src/index.ts の 3 者が一致しない場合にビルドを失敗させる。

# 1. package.json と src/index.ts の version / VERSION を同じ値に更新してコミット
#    （例: 0.1.0 → 0.2.0）
# 2. タグを付けて push
git tag v0.2.0
git push origin v0.2.0

RC 等のプレリリース版（タグに - を含む場合、例: v0.2.0-rc.1）は GitHub Release が prerelease として作成され、Docker イメージに :latest は付与されない。

GitHub App 権限

最小限必要な権限:

権限	レベル
Metadata	読み取り
Contents	読み取り
Pull requests	読み取り・書き込み
Issues	読み取り・書き込み

詳細は docs/permissions.md を参照。

セキュリティ

• GitHub App private key は環境変数で管理し、リポジトリにコミットしない
• Webhook 署名検証は必須
• すべての操作に対して repository allowlist を適用する

詳細は docs/security.md を参照。

ライセンス

MIT