GitHub Appセットアップ

GitHub Appセットアップ

Themisは Themis AI Agent というGitHub App経由でGitHubに認証します。1つのアプリ登録でデプロイメント上のすべてのスペースをカバーし、各スペースは同じアプリをインストールして独自の installation_id を受け取ります。

なぜGitHub App（PATではなく）なのか

プライベート組織で専用のBotシートが不要です。
インストールごとのレート制限（Botアカウントごとではなく、インストールごとに5k/時間）。
きめ細かいリポジトリ権限。組織の管理者が一度インストールすれば、チーム全体に適用されます。
Webhook配信はアプリにバンドルされており、リポジトリごとに設定する必要がありません。

アプリの登録

デプロイメントごとに一度、あなたのGitHubユーザーまたは組織の下でアプリを登録します。https://github.com/settings/apps/new にアクセスしてください。

基本情報

Name: Themis AI Agent
Homepage URL: デプロイメントURL（例: https://3coms.dev）
Where can this GitHub App be installed: Any account

ユーザーの識別と認可

Callback URL: https://<your-deployment>/github_app/oauth/callback
☑️ Request user authorization (OAuth) during installation
☑️ Expire user authorization tokens
☐ Enable Device Flow

インストール後

Setup URL: 空欄のまま（インストール中OAuthが有効になっている場合は無効）
☑️ Redirect on update

Webhook

☑️ Active
URL: https://<your-deployment>/webhooks/github
Secret: ランダムな16進文字列を生成 — Rails credentialsに保存します

リポジトリ権限

権限	レベル	理由
Contents	Read & write	コード生成のコミット
Pull requests	Read & write	レビュー、インラインコメント、PR作成
Issues	Read & write	Sentry → issue、コメント
Checks	Read	CIステータス
Commit statuses	Read	レガシーCIステータス
Actions	Read	ワークフロー実行結果
Workflows	Read & write	`.github/workflows/*` の変更をプッシュ
Metadata	Read	自動付与

組織権限

権限	レベル
Members	Read

アカウント権限（user-to-server OAuth）

権限	レベル
Email addresses	Read

購読するイベント

Pull request, Pull request review, Pull request review comment, Issue comment, Issues, Push, Check run, Check suite, Workflow run, Release, Installation target。

アプリを作成したら、アプリ設定ページから秘密鍵を生成し、.pem ファイルをダウンロードします。

認証情報の保存

暗号化された認証情報に追加します：

bin/rails credentials:edit --environment=production

github_app:
  app_id: <アプリページの整数>
  client_id: <アプリページの文字列>
  client_secret: <アプリページの文字列>
  webhook_secret: <Webhookに設定したランダムな16進文字列>
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

アプリのスラグがデフォルトの themis-ai-agent と異なる場合（別の名前を付けた場合など）、次も追加してください：

github_app:
  app_slug: <your-slug>

認証情報を更新したら、Railsサーバーを再起動してください。

スペースへのインストール

スペースのオーナー/マネージャーがセルフインストールします：

Space Settings → Connections → GitHub を開きます。
Install GitHub App をクリックします。
GitHubで、個人アカウントまたは組織を選択します。組織の場合、管理者が1回インストールすればメンバー全員に適用されます。
GitHubがThemisにリダイレクトして戻り、インストールIDがスペースにバインドされます。

同じユーザーが「個人用」と「仕事用」のスペースを別々に持ち、それぞれに独自のインストールを持つことができます。

Webhookフロー

GitHubはすべての配信にアプリレベルの webhook_secret で署名します。ThemisはHMACを検証し、ペイロードから installation.id を読み取り、space_channels 上の一意な github_installation_id カラムを介してスペースを解決します。

トークンライフサイクル

Themisはオンデマンドでインストールアクセストークンを発行します。有効期間は1時間で、Themisは55分間キャッシュし、透過的に更新します。トークンはデータベースに保存されることはなく、保存されるのはインストールIDのみです。

トラブルシューティング

“GitHub App is not configured on this deployment” — 認証情報が不足しているか、形式が正しくありません。private_key のYAMLインデントを再確認してください（| のリテラルブロックが必要です）。

Webhookが401を返す — credentials内のアプリレベル webhook_secret が、アプリ登録で設定したシークレットと一致していません。

Webhookが No space bound to installation <id> を返す — スペースは切断されましたが、GitHub側ではアプリがまだインストールされています。Space Settingsから再インストールするか、https://github.com/settings/installations でGitHubからアンインストールしてください。