feat(github-app): per-repo Octokit resolution and multi-installation queries (#283 PR 2/7)

[coji]

Summary

Issue #283 の実装 stack PR 2/7 — query / mutation / Octokit 解決層を複数 installation 対応にする。アプリケーションの動作はまだ変えない（fallback で互換維持）。

設計根拠: docs/rdd/issue-283-multiple-github-accounts.md
作業計画: docs/rdd/issue-283-work-plan.md

依存: #288 (PR 1: schema)

変更内容

query 層 (app/services/github-integration-queries.server.ts)

• getGithubAppLinks(orgId) 配列返却（ORDER BY createdAt ASC で決定的順序）
• getGithubAppLinkByInstallationId(installationId) 追加
• assertInstallationBelongsToOrg(orgId, installationId) 追加 — クライアント由来の installationId をサーバ側で検証する境界 guard
• getGithubAppLink() は最古の active link を返す互換 shim（@deprecated）

mutation 層 (app/services/github-app-mutations.server.ts)

• disconnectGithubAppLink(orgId, installationId) 追加 — 単一 installation の soft-delete + 最後の active を失った時のみ method='token' に戻す + audit log 書き込み
• 1 transaction 内で完結（idempotent）
• disconnectGithubApp() は legacy UI 互換 wrapper として 1 transaction で全 link 一括 soft-delete に書き換え（@deprecated）

audit log writer (app/services/github-app-link-events.server.ts) 新規追加

• logGithubAppLinkEvent() helper
• event_type / source / status の string union 型を export
• Kysely<DB> | Transaction<DB> を受け取り、呼び出し側のトランザクションに乗せられる
• PR 1 で追加した github_app_link_events table の 初回 writer（disconnect 経由）

Octokit 解決 (app/services/github-octokit.server.ts)

• resolveOctokitForInstallation(installationId) 追加
• resolveOctokitForRepository({ integration, githubAppLinks, repository }) 追加 — repository ごとの解決
  • repository.githubInstallationId がセットされている場合は厳密にそれを使う（suspended は弾く）
  • github_app モードで未割当の repository に対する移行期間 fallback:
    • active link 1 件 → そのまま使う
    • 0 件 → エラー（PAT 自動 fallback はしない、RDD ルール）
    • 2+ 件 → エラー（曖昧、明示的な assignment が必要）
  • token モード: privateToken があれば PAT、無ければ未接続エラー
• IntegrationForOctokit.method を 'token' | 'github_app' | (string & {}) のユニオンに型を絞る
• resolveOctokitFromOrg() は legacy 互換 wrapper（@deprecated、PR 4 で削除予定）

batch shape 更新 (batch/db/queries.ts)

• getGithubAppLinkByOrgId → getGithubAppLinksByOrgId（配列返却）
• getAllGithubAppLinks を Map.groupBy で書き換え
• getOrganization() / listAllOrganizations() が githubAppLinks: [] を返すよう変更

crawl / backfill ジョブ (app/services/jobs/{crawl,backfill}.server.ts)

• 単一 Octokit 共有から per-repository 解決に変更
• load-organization step 内で github_app + active 0 / token + privateToken null の早期エラー検出
• repository ループ内で resolveOctokitForRepository() を呼び、解決失敗時は warn ログ + skip（crawl 全体は止めない）

tsconfig

• lib を ES2024 に bump（Map.groupBy を使うため）

tests

• app/services/github-octokit.server.test.ts に resolveOctokitForRepository の 11 ケース追加
  • 明示 installation id (一致 / 不一致 / suspended)
  • 移行期間 fallback (active 1 / 0 / 2+ / suspended 除外)
  • token モード (PAT あり / なし)
  • integration null

満たす受入条件

• feat: report with number of comments #6: crawl.server.ts / backfill.server.ts が repository ごとに対応 installation の Octokit を使う

Stack 位置

PR 1 (#288): schema
└ [PR 2: query/octokit] ← this PR
  └ PR 3 (webhook/membership)
    └ PR 4 (UI)
      └ PR 5 (repo UI)
        └ PR 6 (backfill)
          └ PR 7 (strict)

後続 PR への影響

• PR 3: webhook handler 群がここで追加した getGithubAppLinkByInstallationId / logGithubAppLinkEvent / canonical reassignment helper（PR 3 で実装）を使う
• PR 4: UI loader / action から getGithubAppLink() を getGithubAppLinks() に移行 + assertInstallationBelongsToOrg を loader 境界で呼ぶ
• PR 7: 移行期間 fallback (activeLinks.length === 1 分岐) を削除し、github_installation_id IS NULL を strict エラーにする

テスト

• `pnpm validate` (lint / format / typecheck / build / test 全 331 tests)
• `resolveOctokitForRepository` の主要 11 ケースをユニットテストで検証

🤖 Generated with Claude Code

Summary by CodeRabbit

リリースノート

• 新機能

  • GitHub Appのリンク接続・切断イベントに対する監査ログ機能を追加しました。

• バグ修正

  • リポジトリごとのGitHub認証解決ロジックを改善し、複数のアクティブなリンク存在時のエラーハンドリングを強化しました。
  • GitHub Appの削除状態をより厳密に追跡するようにしました。

• 改善

  • GitHub統合に関する検証とエラー処理を堅牢化しました。

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

ウォークスルー

GitHub Appの複数インストレーション対応を実現するため、監査ログ機能の追加、インストレーション単位でのOctokit解決、マルチリンク対応のクエリ更新、ジョブの内部実装変更が行われました。これらは単一インストレーション前提の既存コードを段階的に置き換え、組織あたり複数のGitHub Appリンクの管理を可能にします。

変更内容

コホート / ファイル	概要
GitHub App リンク監査ログ app/services/github-app-link-events.server.ts	新しいサーバー側サービスモジュールとして、型付きの監査ログイベントドメインモデルを定義。logGithubAppLinkEvent非同期関数により、githubAppLinkEventsテーブルに機構化データとともにエントリを記録します。
GitHub App マテーション app/services/github-app-mutations.server.ts	インストレーション単位の新規関数disconnectGithubAppLinkを追加し、ソフトデリート時にlink_deleted監査イベントを記録。既存disconnectGithubAppは「全削除」ヘルパーに変更し、インストレーション単位ごとに監査ログを出力します。
GitHub App 統合クエリ app/services/github-integration-queries.server.ts	複数リンク対応としてgetGithubAppLinks（全アクティブリンク配列返却）を新規追加。既存関数を更新し、getGithubAppLinkは非推奨化、getGithubAppLinkByInstallationIdは選択列セットを拡張。インストレーション所属検証関数assertInstallationBelongsToOrgを追加します。
Octokit 解決機能 app/services/github-octokit.server.ts, app/services/github-octokit.server.test.ts	新しい型IntegrationMethod、IntegrationForOctokit、GithubAppLinkForOctokit、RepositoryForOctokitを追加。インストレーション単位解決関数resolveOctokitForInstallationとリポジトリ単位解決関数resolveOctokitForRepositoryを新規追加。resolveOctokitFromOrgを非推奨化。テスト層でstubGithubAppEnvヘルパーと新規テストスイートを追加します。
ジョブ更新 app/services/jobs/backfill.server.ts, app/services/jobs/crawl.server.ts	org-scoped認証検証から、per-repository Octokit解決への移行。ジョブステップ内でインテグレーション方式チェックとリポジトリ単位でのOctokit構築を実施。エラーハンドリングを個別リポジトリ段階で行い、全体失敗を回避します。
バッチクエリ batch/db/queries.ts	githubAppLinkColumns選択セットを拡張。getGithubAppLinkByOrgIdをマルチ行返却のgetGithubAppLinksByOrgIdに置き換え。getAllGithubAppLinksと統計関数をMap.groupByで複数レコード対応に変更。出力型のgithubAppLinkを配列githubAppLinksに統一します。
TypeScript 設定 tsconfig.json	コンパイラオプション lib を ES2022 から ES2024 に更新。

シーケンス図

sequenceDiagram
    participant Job as バックフィル/クロールジョブ
    participant Query as 統合クエリ層
    participant Integration as インテグレーション取得
    participant OctokitRes as Octokit解決
    participant GithubAPI as GitHub API

    Job->>Query: 組織と全リポジトリ取得
    Query-->>Job: 組織、統合メソッド、リンク配列

    Job->>Job: リポジトリをループ

    alt github_app メソッド
        Job->>Integration: githubAppLinks 参照
        Integration-->>Job: アクティブリンク確認
        
        alt 明示的installationId あり
            Job->>OctokitRes: resolveOctokitForRepository<br/>(統合, リンク, リポジトリ)
            OctokitRes->>OctokitRes: 一致するリンク検索
            OctokitRes->>OctokitRes: サスペンド状態チェック
            OctokitRes-->>Job: リポジトリ用Octokit
        else 明示的installationId なし
            Job->>OctokitRes: resolveOctokitForRepository<br/>(統合, リンク, リポジトリ)
            OctokitRes->>OctokitRes: アクティブリンク フィルタ
            OctokitRes->>OctokitRes: 件数チェック<br/>(0 or >1 なら例外)
            OctokitRes-->>Job: リポジトリ用Octokit
        end
    else token メソッド
        Job->>OctokitRes: resolveOctokitForRepository<br/>(統合, リンク, リポジトリ)
        OctokitRes->>OctokitRes: privateToken チェック
        OctokitRes-->>Job: トークン用Octokit
    end

    Job->>GithubAPI: Octokit経由でAPI呼び出し
    GithubAPI-->>Job: データ取得
    Job->>Job: バックフィル/クロール実行

Loading

sequenceDiagram
    participant User as ユーザー
    participant Mutation as GitHubアプリマテーション
    participant Query as クエリ層
    participant DB as データベース
    participant Audit as 監査ログサービス

    User->>Mutation: disconnectGithubAppLink<br/>(organizationId, installationId)
    
    Mutation->>Query: インストレーション検証
    Query->>DB: 所属確認クエリ
    DB-->>Query: インストレーションデータ
    Query-->>Mutation: 検証完了

    Mutation->>DB: トランザクション開始
    
    Mutation->>DB: ソフトデリート実行<br/>(deletedAt 設定)
    DB-->>Mutation: 更新行数
    
    Mutation->>Query: 他アクティブリンク確認
    Query->>DB: 残存リンククエリ
    DB-->>Query: リンク数
    
    alt 最後のリンクだった場合
        Mutation->>DB: integrations.method<br/>を 'token' に変更
        Mutation->>DB: appSuspendedAt をクリア
    end
    
    Mutation->>Audit: logGithubAppLinkEvent<br/>('link_deleted', ...)
    Audit->>DB: githubAppLinkEvents<br/>に挿入
    
    Mutation->>DB: トランザクションコミット
    DB-->>Mutation: 完了
    Mutation-->>User: 切断成功

Loading

推定コードレビュー工数

🎯 4 (Complex) | ⏱️ ~75 分

関連する可能性のあるissue

• GitHub App複数インストレーション対応（issue #283）：このPRで実装される複数githubAppLinks、インストレーション単位の切断、リポジトリ単位のOctokit解決、クエリ変更が、直接的にこのissueの目的に対応します。

関連する可能性のあるPR

• PR #287：複数GitHub Appインストレーション対応（マルチローgithubAppLinks、Octokit解決、クエリ/マテーション、バックフィル動作）として、このPRの基盤となる変更を提供します。
• PR #288：このPRの新規イベント監査ログサービスとgithub_app_link_eventsテーブル参照が、PR #288で導入されたスキーマに直接依存します。
• PR #245：GitHub Appマイグレーションで導入・修正されたgithubAppLinks・disconnect処理・integrations経路に対し、このPRのイベントログと切断ロジックが直接動作します。

詩

🐰 複数のインストール、今や花開き
リンク単位での切断、監査ログ記す
Octokit、リポジトリごとに賢く選び
型安全にマルチ対応、やさしく統合
スキーマはマッピング、データベースで踊る

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main changes: per-repository Octokit resolution and multi-installation query support, which are the core improvements across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-283-query-octokit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coji]

• feat(github-app): per-repo Octokit resolution and multi-installation queries (#283 PR 2/7) #296 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coji]

Merge activity

• Apr 8, 11:11 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 8, 11:11 AM UTC: @coji merged this pull request with Graphite.