GitHub App session summary (UTF-8)

github-app.utf8.md

GitHub App — セッションまとめ

日時: 2026-04-24

1) 発端

• リポジトリの「Installed GitHub Apps」画面で There aren't any GitHub Apps installed on this repository. と表示され、新規作成ボタンが見当たらない問題を確認。
• これは「インストール済みアプリの一覧」ページであり、新規作成は Developer settings 側（Account/Organization の Settings → Developer settings → GitHub Apps）で行う必要がある。

2) 最低限用意するもの（チェックリスト）

• GitHub アカウント（組織で作る場合はオーナー権限）
• App 名、Homepage URL
• Webhook を使うなら HTTPS の受信エンドポイント（開発は ngrok 等で代替）
• Webhook secret（署名検証用）
• プライベートキー（.pem、GitHub で Generate a private key を実行してダウンロード）
• テスト用リポジトリ／組織
• シークレット管理（環境変数やシークレットマネージャ）
• 最小権限の設計（必要な Permissions と Events のみ）

3) 作成の流れ（簡潔）

1. GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
   • または: https://github.com/settings/apps/new
2. 必要項目を入力（Webhook URL / secret / permissions / events 等）
3. 作成後にプライベートキーを生成して保存
4. App のページから「Install App」で対象リポジトリへインストール

4) 認証の概要（短）

• App の private key で JWT を作成（iss=App ID、exp 最大10分）
• JWT でインストールIDを確認 → POST /app/installations/:installation_id/access_tokens でインストールトークンを取得
• 取得したトークンで API 呼び出し

Node（Octokit）最小例

import { createAppAuth } from "@octokit/auth-app";
import { Octokit } from "octokit";

const auth = createAppAuth({
  appId: Number(process.env.GH_APP_ID),
  privateKey: process.env.GH_PRIVATE_KEY,
  installationId: Number(process.env.GH_INSTALLATION_ID),
});

const installationAuth = await auth({ type: "installation" });
const octokit = new Octokit({ auth: installationAuth.token });
await octokit.request("GET /repos/{owner}/{repo}", { owner, repo });

5) Webhook 署名検証（短）

import crypto from "crypto";

function verify(rawBody, signature, secret) {
  const hmac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const expected = `sha256=${hmac}`;
  const a = Buffer.from(signature || "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

• Express を使う場合は express.raw({ type: "application/json" }) で生の body を取得する。

6) 代表的ユースケース

• PR 自動コメント / ラベリング / 自動マージ
• Checks API を使った CI 結果の表示・アノテーション
• 依存更新 PR の自動作成（Dependabot 風）
• セキュリティスキャン結果を Issue 化 / 通知

7) 運用上の注意（短）

• プライベートキーは一度しかダウンロードできない：必ず安全に保管
• トークン有効期限に注意（JWT は短い、インストールトークンも短時間）
• Webhook は必ず署名検証を行う
• HTTPS 必須（開発時はトンネルを使用）

参考

• Building GitHub Apps: https://docs.github.com/en/developers/apps/building-github-apps
• Authenticating as a GitHub App: https://docs.github.com/en/developers/apps/authenticating-with-github-apps