mirror of https://github.com/buster-so/buster.git
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# @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`):
|
|
```bash
|
|
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
|
|
```typescript
|
|
import { getInstallationToken } from '@buster/github';
|
|
|
|
const token = await getInstallationToken(installationId);
|
|
// Returns: { token, expires_at, permissions, repository_selection }
|
|
```
|
|
|
|
### Verify Webhook Signature
|
|
```typescript
|
|
import { verifyGitHubWebhookSignature } from '@buster/github';
|
|
|
|
const isValid = verifyGitHubWebhookSignature(payload, signature);
|
|
```
|
|
|
|
## Testing Locally
|
|
|
|
1. **Set up ngrok** for webhook forwarding:
|
|
```bash
|
|
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 |