v2.0.0-alpha.5: GitHub App Integration

[norberia]

GitHub App Integration

Closes #115

Summary

This PR implements GitHub App integration to replace the legacy GitHub OAuth approach for repository operations. The integration provides better security, fine-grained permissions, and a streamlined user experience.

Changes

Phase 1: Backend Infrastructure ✅

• Schema: Added GitHubAppInstallation model and new GitHub fields on Project (githubAppInstallationId, githubRepoId, githubRepoFullName)
• Service Layer: Created lib/services/github-app.ts with JWT generation, installation token caching, and webhook signature verification
• Repository Layer: Added lib/repo/github.ts for installation CRUD and project-repo linking
• API Routes:
  • app/api/github/app/callback/route.ts - Handles GitHub App installation callback with ownership verification
  • app/api/github/app/webhook/route.ts - Processes installation lifecycle events (created/deleted/suspend/unsuspend)

Phase 2: Frontend UI ✅

• Settings Page: app/settings/page.tsx with GitHub integration status
• Import Dialog: components/dialog/import-github-dialog.tsx with 3-step flow (GitHub identity → GitHub App → Repo selection)
• Components:
  • components/github/github-status-card.tsx - GitHub connection status
  • components/github/repo-selector.tsx - Searchable repo selector
  • components/github/installation-list.tsx - Installation management

Phase 3: Octokit + Merged OAuth ✅

• Migrated from manual fetch to @octokit/rest and @octokit/app
• Enabled "Request user authorization during installation" on GitHub App
• Merged authentication and authorization into a single flow
• Fixed OAuth token exchange endpoint (use github.com/login/oauth/access_token instead of API route)
• Fixed callback response format (HTML with postMessage for popup communication)

Phase 4: Code Migration ✅

• Updated components/layout/repo-status-indicator.tsx to prioritize new fields with fallback
• Updated app/(dashboard)/projects/[id]/github/page.tsx with new field strategy
• Updated lib/services/repoService.ts:
  • createGithubRepo() returns repoId and repoFullName
  • initializeRepo() saves both new and legacy fields
  • pushToGithub() uses githubRepoFullName || githubRepo pattern

Backward Compatibility

The implementation follows an expand-contract migration strategy:

const repoFullName = project.githubRepoFullName || project.githubRepo

• ✅ Legacy data (only githubRepo) continues to work
• ✅ New data uses the more accurate fields
• ✅ Mixed data prioritizes new fields
• ✅ No forced data migration required

User Flow

GitHub OAuth (Identity) → GitHub App Installation → Select Repo → Link to Project
UserIdentity             → GitHubAppInstallation  → Project.githubRepoId

Environment Variables Required

GITHUB_APP_ID=<App ID>
GITHUB_APP_PRIVATE_KEY=<PEM private key>
GITHUB_APP_WEBHOOK_SECRET=<Webhook secret>
GITHUB_APP_CLIENT_ID=<OAuth App Client ID>
GITHUB_APP_CLIENT_SECRET=<OAuth App Client Secret>
NEXT_PUBLIC_GITHUB_APP_NAME=<App slug for install URL>

Testing

• ✅ Lint passes
• ✅ Build succeeds
• ✅ GitHub App installation flow works
• ✅ OAuth code exchange succeeds
• ✅ UserIdentity and GitHubAppInstallation created correctly
• ✅ Popup auto-closes after installation
• ✅ Frontend state updates correctly

Remaining Work (Phase 5 - Optional)

Phase 5 (Cleanup) is optional and can be deferred:

• Remove deprecated githubRepo field from schema
• Remove legacy GitHub OAuth routes
• Update documentation

This can be done after 3-6 months when legacy data is no longer needed.

[github-actions]

✅ PR Check Results: Passed

Build Checks

Check	Status
Lint & Build	✅ Passed
Docker Build	✅ Passed

✨ Great work!

All checks passed successfully. Your PR is ready for review.

Details:

• ✅ Code quality verified (linting passed)
• ✅ Build successful
• ✅ Docker image build verified (linux/amd64)
  Commit: 720cfa6696a0ab9a622fbe690c6da8b95ddf9493
  Branch: feat/github-app-integration

🔗 View Details:

• Lint & Build
• Docker Build