146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
# GitHub App Setup Guide
|
|
|
|
This project uses **GitHub App** for authentication, which provides better security and more fine-grained permissions compared to OAuth Apps.
|
|
|
|
## Why GitHub App?
|
|
|
|
- **Fine-grained permissions**: Request only the permissions you need
|
|
- **Better security**: Separate user authentication from app installation
|
|
- **Modern approach**: Recommended by GitHub for new applications
|
|
- **Flexible**: Support both user authentication and app-level operations
|
|
|
|
## Creating a GitHub App
|
|
|
|
### 1. Navigate to GitHub App Settings
|
|
|
|
Go to [GitHub Developer Settings](https://github.com/settings/apps) and click **New GitHub App**.
|
|
|
|
### 2. Fill in Basic Information
|
|
|
|
- **GitHub App name**: Your app name (e.g., "Project Dashboard Dev")
|
|
- **Homepage URL**: `http://localhost:5173` (for development)
|
|
- **Callback URL**: `http://localhost:5173/callback`
|
|
- **Webhook**: Uncheck "Active" (unless you need webhooks)
|
|
|
|
### 3. Configure Permissions
|
|
|
|
Under **Repository permissions**, select:
|
|
|
|
- **Contents**: Read-only (to read repository data)
|
|
- **Metadata**: Read-only (required, automatically enabled)
|
|
- **Commit statuses**: Read-only (for commit statistics)
|
|
|
|
Under **Account permissions**, select:
|
|
|
|
- **Email addresses**: Read-only (to get user email)
|
|
|
|
### 4. Where can this GitHub App be installed?
|
|
|
|
Choose:
|
|
|
|
- **Any account** (allows any user to authenticate)
|
|
|
|
### 5. Create the App
|
|
|
|
Click **Create GitHub App**.
|
|
|
|
### 6. Get Your Credentials
|
|
|
|
After creation, you'll see:
|
|
|
|
1. **App ID**: Found at the top of the app settings page
|
|
2. **Client ID**: Under "About" section
|
|
3. **Client secrets**: Click "Generate a new client secret"
|
|
|
|
### 7. Update Your `.env` File
|
|
|
|
Copy the credentials to your `.env` file:
|
|
|
|
```env
|
|
GITHUB_APP_ID="123456"
|
|
GITHUB_APP_CLIENT_ID="Iv1.abc123def456"
|
|
GITHUB_APP_CLIENT_SECRET="your-client-secret-here"
|
|
```
|
|
|
|
## User Authentication Flow
|
|
|
|
The authentication flow for GitHub Apps is similar to OAuth Apps:
|
|
|
|
1. **Frontend**: Redirect user to GitHub authorization URL:
|
|
|
|
```
|
|
https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID
|
|
```
|
|
|
|
2. **GitHub**: User authorizes the app and is redirected back with a `code`
|
|
|
|
3. **Frontend**: Send the `code` to your backend API:
|
|
|
|
```
|
|
POST /auth/login
|
|
{ "code": "received_code" }
|
|
```
|
|
|
|
4. **Backend**:
|
|
- Exchange code for access token
|
|
- Fetch user information
|
|
- Generate JWT token
|
|
- Return to frontend
|
|
|
|
## Frontend Integration Example
|
|
|
|
```typescript
|
|
// Redirect to GitHub for authorization
|
|
const clientId = 'YOUR_GITHUB_APP_CLIENT_ID'
|
|
const redirectUri = 'http://localhost:5173/callback'
|
|
const authUrl = `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}`
|
|
|
|
window.location.href = authUrl
|
|
|
|
// In your callback page, extract the code
|
|
const urlParams = new URLSearchParams(window.location.search)
|
|
const code = urlParams.get('code')
|
|
|
|
// Send to backend
|
|
const response = await fetch('http://localhost:3333/auth/login', {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({ code }),
|
|
})
|
|
|
|
const { data } = await response.json()
|
|
const token = data.token // Use this JWT for subsequent API calls
|
|
```
|
|
|
|
## Differences from OAuth Apps
|
|
|
|
| Feature | OAuth App | GitHub App |
|
|
| ----------- | --------------------- | ----------------------------------------- |
|
|
| Permissions | Coarse-grained scopes | Fine-grained permissions |
|
|
| Token Type | User access token | User access token + Installation token |
|
|
| Rate Limits | 5,000 requests/hour | 5,000 requests/hour (user) + 15,000 (app) |
|
|
| Recommended | Legacy | **✓ Modern** |
|
|
|
|
## Troubleshooting
|
|
|
|
### "Bad verification code" error
|
|
|
|
- Ensure the code hasn't expired (codes are single-use and expire after 10 minutes)
|
|
- Check that your Client ID and Client Secret are correct
|
|
|
|
### "Not found" error
|
|
|
|
- Verify your GitHub App is set to "Any account" installation
|
|
- Check that the callback URL matches your frontend URL
|
|
|
|
### API Rate Limiting
|
|
|
|
- User authentication has 5,000 requests/hour per user
|
|
- Consider implementing Redis caching (already included in this project)
|
|
|
|
## Additional Resources
|
|
|
|
- [GitHub Apps Documentation](https://docs.github.com/en/apps)
|
|
- [User-to-Server Authentication](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)
|
|
- [GitHub App Permissions](https://docs.github.com/en/rest/overview/permissions-required-for-github-apps)
|