Route files: app/api/install/*/route.ts Supporting lib: lib/auth/server/installation-service.ts, lib/supabase/installation-repository.ts

GET /api/install/start

File: app/api/install/start/route.ts

Requires an active session. If you’re not signed in, it redirects to /api/auth/start?returnTo=/api/install/start first.

Steps

1. getRequestSession(request) → session lookup
2. No session → redirect to /api/auth/start
3. Generate CSRF (32 bytes base64url random)
4. Create signed install state JWT (HS256): { type: "install", csrf, returnTo, sessionId }, expires 10 min
5. Build GitHub install URL
6. Set gh_install_csrf cookie: httpOnly, secure, sameSite=none, path=/, maxAge=600
7. 302 redirect

Install state JWT

interface InstallState {
  type: 'install';
  csrf: string;
  returnTo: string;
  sessionId: string; // Embedded so callback can find session even if cookie is lost
}

Edge cases

• Session expires during the install flow: the sessionId in the state JWT lets the callback still find it.
• If the app is already installed, GitHub shows a “Configure” page instead. The callback still processes it.

GET /api/install/callback

File: app/api/install/callback/route.ts

GitHub redirects here after the user installs (or configures) the app.

Steps

1. State verification: verify HS256 signature + expiry + type === "install". Fail → 400
2. CSRF validation: gh_install_csrf cookie must equal state.csrf. Fail → 403
3. Installation ID validation: Number.parseInt → must be finite. Fail → 400
4. Validate installation: InstallationService.validateInstallation(id) calls GitHub API to confirm it exists. Fail → 400
5. Session resolution: try getSession(state.sessionId) first, fall back to getRequestSession(request). Fail → 401
6. Merge installation ID: insert into session_installations join table if not already present
7. 302 redirect to returnTo. Delete gh_install_csrf

Error responses

GET /api/install/status

File: app/api/install/status/route.ts

Requires session. Returns 401 if missing.

Response (with installations)

{
  "installed": true,
  "installationIds": [12345, 67890],
  "accounts": [
    {
      "installationId": 12345,
      "accountLogin": "my-org",
      "accountType": "organization",
      "repositoryCount": 18,
      "repositories": [
        {
          "nameWithOwner": "my-org/repo1",
          "url": "https://github.com/my-org/repo1",
          "isPrivate": false
        }
      ],
      "updatedAt": "2026-05-25T10:00:00.000Z"
    }
  ],
  "summary": {
    "totalInstallations": 2,
    "orgInstallations": 1,
    "totalRepositories": 18,
    "totalAccounts": 1,
    "organizationAccounts": 1,
    "userAccounts": 0
  }
}

Response (no installations)

{
  "installed": false,
  "installationIds": [],
  "accounts": [],
  "summary": {
    "totalInstallations": 0,
    "orgInstallations": 0,
    "totalRepositories": 0,
    "totalAccounts": 0,
    "organizationAccounts": 0,
    "userAccounts": 0
  }
}

How it works

For each installation ID in the session:

1. Call InstallationService.getInstallationRepositories(id)
2. Uses installation-scoped Octokit to fetch repository data
3. Returns snapshot with account info, repo count, and repository list

POST /api/install/complete

File: app/api/install/complete/route.ts

Requires session. 401 if missing.

Request body

{ "installationId": 12345 }

Response

{ "ok": true, "installationId": 12345 }

Logic:

1. Validate installationId is a finite number
2. Validate installation exists via GitHub API
3. Insert into session_installations join table (if not already present)
4. Update session in Supabase

Webhook-driven updates

The POST /api/install/webhook endpoint (see Webhook API) handles GitHub App events and updates github_installations automatically:

• New installs appear in the DB immediately
• Deletes remove the row immediately
• Suspensions update the status immediately
• Repository changes refresh the installation metadata

The GET /api/install/status endpoint reads from this cached data rather than calling GitHub on every request.

Related

• Webhook API — GitHub App webhook handler
• Organization Routes — org list and detail
• Auth Routes — OAuth sign-in flow
• Database Schema — github_installations table