buster/packages/github

@buster/github

GitHub App integration package for managing installations, tokens, and webhook verification.

Features

• GitHub App OAuth Flow: Properly associate installations with organizations
• Token Management: Automatic token generation, caching, and refresh with 1-hour expiry
• Webhook Verification: Secure webhook signature validation using HMAC-SHA256
• Installation Lifecycle: Handle installation, suspension, unsuspension, and deletion events

Installation Flow

OAuth-based Installation (Recommended)

This flow ensures proper association between GitHub installations and your organization:

1. Initiate Installation: User clicks "Install GitHub App" in your application

   GET /api/v2/github/installation/initiate
   

   Returns a redirect URL with a secure state parameter

2. User Installs App: User is redirected to GitHub to install the app

3. Complete Installation: GitHub redirects back with state and installation_id

   GET /api/v2/github/installation/complete?state=xxx&installation_id=yyy
   

   Associates the installation with the user's organization

Webhook Events

The app also handles webhook events for installation lifecycle:

• installation.created - New installation (requires OAuth flow for proper association)
• installation.deleted - App uninstalled
• installation.suspend - App suspended by GitHub
• installation.unsuspend - App unsuspended

API Endpoints

OAuth Flow

• GET /api/v2/github/installation/initiate - Start installation flow (requires auth)
• GET /api/v2/github/installation/complete - Complete installation (state validation)

Token Management

• GET /api/v2/github/installations/:installationId/token - Get installation token (requires auth)
• GET /api/v2/github/installations/refresh - Refresh token for user's org (requires auth)

Webhooks

• POST /api/v2/github/installation/callback - GitHub webhook endpoint (signature verified)

Configuration

Required environment variables (set in root .env):

GITHUB_APP_ID=your_app_id
GITHUB_APP_PRIVATE_KEY_BASE64=base64_encoded_private_key
GITHUB_WEBHOOK_SECRET=your_webhook_secret
GITHUB_APP_NAME=your_app_name  # Used in OAuth redirect URLs

Token Storage

Tokens are stored securely in Supabase Vault with automatic expiry handling:

• Tokens expire after 1 hour (GitHub limitation)
• 5-minute buffer before expiry for safety
• Automatic refresh on expired token access

Usage

Get Installation Token

import { getInstallationToken } from '@buster/github';

const token = await getInstallationToken(installationId);
// Returns: { token, expires_at, permissions, repository_selection }

Verify Webhook Signature

import { verifyGitHubWebhookSignature } from '@buster/github';

const isValid = verifyGitHubWebhookSignature(payload, signature);

Testing Locally

1. Set up ngrok for webhook forwarding:

   ngrok http 3002
   

2. Configure GitHub App:

   • Webhook URL: https://your-ngrok-id.ngrok.io/api/v2/github/installation/callback
   • Callback URL: http://localhost:3002/api/v2/github/installation/complete

3. Install the App:

   • Start from your application: /api/v2/github/installation/initiate
   • Complete installation on GitHub
   • Callback will associate installation with your organization

Security

• All webhook requests are verified using HMAC-SHA256
• Installation tokens are scoped to specific permissions
• OAuth state parameters prevent CSRF attacks
• Tokens are never logged or exposed