feat: add feature to let users connect their repositories with perlify

[sourabhrathourr]

GitHub App Installation & Webhook Integration Documentation

Overview

This documentation covers the setup and handling of GitHub App installations and webhooks in a Next.js application using Drizzle ORM and Neon Database.

Database Schema

export const installations = pgTable('installation', {

  id: text('id').primaryKey(),

  userId: text('userId')

    .notNull()

    .references(() => users.id, { onDelete: 'cascade' }),

  installationId: text('installationId').notNull(),

  accountName: text('accountName').notNull(),

  repositoryIds: text('repositoryIds').array(),

  createdAt: timestamp('createdAt').defaultNow(),

  updatedAt: timestamp('updatedAt').defaultNow(),

})

Required Environment Variables

DATABASE_URL=your_neon_db_url

GITHUB_WEBHOOK_SECRET=your_webhook_secret

NEXT_PUBLIC_GITHUB_APP_NAME=your_github_app_name

GITHUB_APP_ID=your_app_id

GITHUB_APP_PRIVATE_KEY="your_private_key"

Installation Steps

2. GitHub App Configuration

• Set Webhook URL: https://your-domain.com/api/github/webhook
• Required permissions:
  • Repository: Read
  • Pull requests: Read & Write
  • Metadata: Read

3. Development Setup

# Start development server

yarn dev

# Start ngrok tunnel (for local development)

yarn tunnel

Webhook Handler Implementation

The webhook handler (app/api/github/webhook/route.ts) processes GitHub App installation events and manages repository connections:

1. Verifies webhook signature
2. Handles installation events:
   • created: Creates new installation record
   • added/removed: Updates repository list
3. Links installations to authenticated users via GitHub accounts

Technical Notes

• Uses Drizzle ORM with Neon Database
• Maintains referential integrity between users and installations
• Handles GitHub webhook events securely
• Supports repository selection updates
• Integrates with Next.js Auth.js for user authentication

Error Handling

The webhook handler includes comprehensive error handling for:

• Invalid webhook signatures
• Missing user accounts
• Database constraints
• Installation conflicts

API Response Codes

• 200: Success
• 401: Invalid signature
• 404: User not found
• 500: Internal server error

References

• GitHub App Installation Auth(1)
• GitHub Webhook Events(2)

[linear]

PER-38 feat: add feature to let users connect their repositories with perlify