GitHub App 基盤 仕様書

CREATE TABLE github_integrations (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL UNIQUE REFERENCES projects(id) ON DELETE CASCADE,
    installation_id BIGINT NOT NULL,
    repo_owner VARCHAR NOT NULL,
    repo_name VARCHAR NOT NULL,
    access_token_enc TEXT NOT NULL,
    token_expires_at TIMESTAMPTZ NOT NULL,
    created_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

1. テナントオーナーが設定画面の「GitHub と連携」をクリック
   → フロントが GET /v1/tenants/{tid}/projects/{pid}/github/install を呼ぶ

2. バックエンドが CSRF 対策のための state を生成・保存:
   - state = 32 バイト乱数（URL-safe base64）
   - Redis に state をキー、{ tenant_id, project_id, user_id } を値として保存（TTL: 10 分）
   → GitHub App インストール URL へリダイレクト:
     https://github.com/apps/{APP_NAME}/installations/new
       ?state={state}

3. ユーザーがリポジトリを選択してインストール後、GitHub がコールバックへリダイレクト:
   GET /v1/github/callback?installation_id=12345&state={state}

4. バックエンドが state を検証:
   - Redis から state を取得（存在しない・期限切れ → 400 Bad Request）
   - Redis から削除（再利用防止）
   - state に紐付く { tenant_id, project_id, user_id } を復元

5. セッションユーザーが state の user_id と一致するか確認（不一致 → 403）

6. installation_id を使って Installation Access Token を取得

7. トークンを AES-256-GCM で暗号化して DB に保存（project_id で github_integrations を UPSERT）

8. 設定完了 → フロントの設定画面（/settings/github）へリダイレクト

202 Accepted  →  Location: https://github.com/apps/{APP_NAME}/installations/new?state=xxx

API 呼び出し前:
  token_expires_at < now() + 5min → GitHub API で再取得 → DB 更新 → 使用
  それ以外 → DB の暗号化済みトークンを復号して使用

{
  "installation_id": 12345,
  "repo_owner": "myorg",
  "repo_name": "myapp"
}

{
  "connected": true,
  "repo_owner": "myorg",
  "repo_name": "myapp",
  "connected_at": "2026-05-27T10:00:00Z"
}

/tenants/{tid}/projects/{pid}/settings/github

┌──────────────────────────────────────────────┐
│ GitHub 連携                                   │
├──────────────────────────────────────────────┤
│ 接続リポジトリ: myorg/myapp          [解除]  │
│                                              │
│ ステータス: ✅ 接続済み                       │
│                                              │
│ [GitHub App を再インストール]                 │
└──────────────────────────────────────────────┘