GitHub App Manual Testing Guide¶

Testing the Installation Flow End-to-End¶

Purpose: Verify that the GitHub App installation flow works correctly in a real environment.

Time Required: 30-45 minutes

Prerequisites: - GitHub App already created in your GitHub account - Local development server running (npm run dev) - Access to your Neon database (to verify records)

Step 1: Verify GitHub App Configuration¶

1.1 Check Environment Variables¶

Verify your .env.local has the required GitHub App credentials:

# Check if these exist
grep "GITHUB_APP" .env.local

Required Variables:

GITHUB_APP_ID=your_app_id
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
GITHUB_APP_WEBHOOK_SECRET=your_webhook_secret
ENABLE_GITHUB_INTEGRATION=true

Action: If any are missing, add them now.

1.2 Find Your GitHub App Settings¶

Go to GitHub.com → Your profile picture → Settings
Scroll down to Developer settings (left sidebar)
Click GitHub Apps
Click on your CodeSlick app

Note the following: - App ID (top of page) - Client ID - Webhook URL (should be set)

Step 2: Configure Callback URL¶

2.1 Update GitHub App Callback URL¶

In your GitHub App settings:

Scroll to Identifying and authorizing users section
Find Callback URL field
Set to: http://localhost:3000/api/github/install/callback
For production: https://codeslick.com/api/github/install/callback
Click Save changes

2.2 Verify Webhook URL¶

Scroll to Webhook section
Verify Webhook URL is set to:
Local: https://your-ngrok-url.ngrok.io/api/github/webhook
Production: https://codeslick.com/api/github/webhook
Verify Webhook secret matches your .env.local

Note: For local testing, you'll need ngrok or similar tunnel for webhooks to work.

Step 3: Start Development Server¶

3.1 Start Next.js Server¶

npm run dev

Expected Output:

  ▲ Next.js 15.x.x
  - Local:        http://localhost:3000
  - Environments: .env.local

 ✓ Ready in 2.5s

3.2 Test Health Check Endpoint¶

Open browser or use curl:

curl http://localhost:3000/api/github/webhook

Expected Response:

{
  "status": "ok",
  "message": "GitHub webhook endpoint is ready",
  "features": {
    "signatureVerification": true,
    "eventLogging": true,
    "prAnalysis": true,
    "statusChecks": true
  },
  "version": "Phase 4 Week 2 Day 4"
}

If you see errors: - status: "disabled" → Set ENABLE_GITHUB_INTEGRATION=true in .env.local - status: "misconfigured" → Check GITHUB_APP_WEBHOOK_SECRET is set

Step 4: Install GitHub App on Test Repository¶

4.1 Create Test Repository (Optional)¶

If you don't have a test repository:

Go to GitHub.com
Click + → New repository
Name: codeslick-test
Visibility: Private (safer for testing)
Click Create repository

4.2 Install GitHub App¶

Option A: Via GitHub App Page 1. Go to your GitHub App settings page 2. Click Public page link (or go to https://github.com/apps/your-app-name) 3. Click Install button (green button)

Option B: Via Repository Settings 1. Go to your test repository 2. Click Settings → Integrations → GitHub Apps 3. Click Add GitHub App 4. Search for your app → Click Install

4.3 Choose Installation Type¶

GitHub will ask:

Where do you want to install this? - Select your personal account or a test organization

Repository access: - Choose Only select repositories - Select your codeslick-test repository - Or choose All repositories (not recommended for testing)

4.4 Click "Install"¶

GitHub will redirect you to:

http://localhost:3000/api/github/install/callback?installation_id=12345678&setup_action=install

Step 5: Verify Installation Flow¶

5.1 Check Browser Redirect¶

Expected Behavior: 1. GitHub redirects to /api/github/install/callback 2. Route processes installation 3. Creates team in database 4. Redirects to /teams/{teamId}?welcome=true

What You Should See: - URL changes to http://localhost:3000/teams/{some-uuid}?welcome=true - Page shows team dashboard (or 404 if page doesn't exist yet)

If You See Error Page: - Check browser console (F12) for JavaScript errors - Check terminal logs for server errors

5.2 Check Server Logs¶

Look at your terminal where npm run dev is running.

Expected Logs:

[Install Callback] Received: installation_id=12345678, setup_action=install
[Install Callback] Processing installation for: your-github-username
[Installation Handler] Creating team for: your-github-username (User)
[Installation Handler] Team created: team_abc123 (your-github-username's Team)
[Installation Handler] Installation created: inst_xyz789
[Installation Handler] Team creation complete: team_abc123
[Install Callback] Team created: team_abc123
[Install Callback] Redirecting to: /teams/team_abc123

If You See Errors: - Missing installation_id → GitHub didn't send installation_id in callback - GitHub App credentials not configured → Check .env.local has GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY - Failed to create team → Database connection issue, check DATABASE_URL

Step 6: Verify Database Records¶

6.1 Check Teams Table¶

Connect to your Neon database and verify the team was created.

Option A: Neon Console 1. Go to console.neon.tech 2. Select your project 3. Click SQL Editor 4. Run query:

SELECT id, name, slug, plan, created_at
FROM teams
ORDER BY created_at DESC
LIMIT 1;

Expected Result:

| id          | name                         | slug                  | plan | created_at          |
|-------------|------------------------------|-----------------------|------|---------------------|
| team_abc123 | your-github-username's Team  | your-username-x7k9    | free | 2025-11-01 14:30:00 |

Option B: Local psql

psql $DATABASE_URL -c "SELECT * FROM teams ORDER BY created_at DESC LIMIT 1;"

6.2 Check GitHub Installations Table¶

SELECT id, team_id, installation_id, account_login, account_type, repositories
FROM github_installations
ORDER BY created_at DESC
LIMIT 1;

Expected Result:

| id          | team_id     | installation_id | account_login | account_type | repositories      |
|-------------|-------------|-----------------|---------------|--------------|-------------------|
| inst_xyz789 | team_abc123 | 12345678        | your-username | user         | ["codeslick-test"]|

Verify: - ✅ team_id matches the team ID from step 6.1 - ✅ installation_id matches the ID from callback URL - ✅ account_login matches your GitHub username - ✅ repositories contains your test repository name

6.3 Check Team Members Table (Optional)¶

If you've already signed in with GitHub OAuth:

SELECT team_id, user_id, role, joined_at
FROM team_members
WHERE team_id = 'team_abc123';

Note: This will be empty until you complete Day 5 (user-team auto-linking).

Step 7: Test Reinstallation Flow¶

7.1 Uninstall GitHub App¶

Go to GitHub.com → Your profile → Settings
Scroll to Applications → Installed GitHub Apps
Find CodeSlick
Click Configure
Scroll down → Click Uninstall
Confirm uninstallation

7.2 Check Server Logs for Webhook¶

Expected Logs (if webhook is working):

[GitHub Webhook] Received: event=installation, delivery=abc-123-def
[GitHub Webhook] Valid webhook received:
  - Event: installation
  - Action: deleted
  - Installation ID: 12345678
[GitHub Webhook] Processing installation deletion
[Installation Handler] Handling uninstall: 12345678
[Installation Handler] Installation unlinked: inst_xyz789

7.3 Verify Soft Delete in Database¶

SELECT team_id, installation_id, account_login, updated_at
FROM github_installations
WHERE installation_id = 12345678;

Expected Result: - ✅ team_id is now NULL (soft deleted) - ✅ Record still exists (not hard deleted) - ✅ updated_at is recent

7.4 Reinstall GitHub App¶

Follow Step 4 again to reinstall.

Expected Behavior: 1. Callback receives installation event 2. Finds existing team (by installation ID) 3. Returns existing team (doesn't create duplicate) 4. Redirects to /teams/{same-team-id}?reinstalled=true

Verify in Logs:

[Installation Handler] Installation already linked to team: team_abc123
[Install Callback] Team found: team_abc123
[Install Callback] Redirecting to: /teams/team_abc123

Verify in Database:

SELECT team_id FROM github_installations WHERE installation_id = 12345678;

✅ team_id is now set again (no longer NULL)
✅ Same team ID as before (no duplicate team created)

Step 8: Test Organization Installation (Optional)¶

If you have access to a GitHub organization:

8.1 Install on Organization¶

Go to your GitHub App page
Click Install
Select an organization (not personal account)
Choose repositories
Click Install

8.2 Verify Team Creation¶

Check database:

SELECT name, slug, plan
FROM teams
ORDER BY created_at DESC
LIMIT 1;

Expected Result:

| name     | slug          | plan |
|----------|---------------|------|
| acme-org | acme-org-b3j2 | free |

Verify: - ✅ Team name is organization name (not "{org}'s Team") - ✅ Slug contains org name + random suffix - ✅ Plan is 'free'

Step 9: Test Repository Selection Changes¶

9.1 Add More Repositories¶

Go to GitHub.com → Your profile → Settings
Applications → Installed GitHub Apps
Find CodeSlick → Click Configure
Under Repository access, add more repositories
Click Save

9.2 Check Webhook for Repository Update¶

Expected Logs:

[GitHub Webhook] Received: event=installation_repositories
[GitHub Webhook] Repositories changed:
  - Added: repo2, repo3
  - Removed: none
[Installation Handler] Updating repos for installation: 12345678
[Installation Handler] Repositories updated: 3 repos

9.3 Verify Database Update¶

SELECT repositories
FROM github_installations
WHERE installation_id = 12345678;

Expected Result:

["codeslick-test", "repo2", "repo3"]

Step 10: Test Error Scenarios¶

10.1 Test Missing Environment Variable¶

Temporarily rename .env.local to .env.local.backup
Restart npm run dev
Try to access callback URL manually:

curl http://localhost:3000/api/github/install/callback?installation_id=12345678

Expected Response:

{
  "error": "GitHub integration is disabled",
  "message": "Set ENABLE_GITHUB_INTEGRATION=true to enable this feature"
}

Restore .env.local and restart server

10.2 Test Invalid Installation ID¶

curl "http://localhost:3000/api/github/install/callback?installation_id=99999999"

Expected Response: - Should redirect to /teams?error=installation_failed - Check logs for error message about GitHub API failure

10.3 Test Database Connection Failure¶

This is harder to test, but you can:

Temporarily set invalid DATABASE_URL in .env.local
Restart server
Try installation flow

Expected: Error page with database connection error

Checklist: What to Verify¶

After completing all steps, verify:

✅ Installation Flow¶

GitHub redirects to callback URL with installation_id
Callback creates team in database
Callback redirects to /teams/{teamId}?welcome=true
No JavaScript errors in browser console
No server errors in terminal

✅ Database Records¶

Team created in teams table
Team has correct name (org name or "username's Team")
Team has unique slug with random suffix
Installation created in github_installations table
Installation linked to team (team_id is set)
Repositories array contains correct repo names

✅ Webhook Events¶

Uninstall event triggers soft delete (team_id → NULL)
Reinstall event links to existing team (no duplicate)
Repository changes update repositories array

✅ Error Handling¶

Feature flag disabled → error message
Missing credentials → error message
Invalid installation ID → graceful error

Troubleshooting Common Issues¶

Issue 1: "GitHub integration is disabled"¶

Cause: ENABLE_GITHUB_INTEGRATION not set to true

Fix:

echo "ENABLE_GITHUB_INTEGRATION=true" >> .env.local

Restart server: npm run dev

Issue 2: "Webhook secret not configured"¶

Cause: GITHUB_APP_WEBHOOK_SECRET missing from .env.local

Fix: 1. Go to GitHub App settings 2. Copy webhook secret 3. Add to .env.local:

GITHUB_APP_WEBHOOK_SECRET=your_secret_here

Issue 3: "Failed to authenticate as GitHub App"¶

Cause: Invalid GITHUB_APP_PRIVATE_KEY or GITHUB_APP_ID

Fix: 1. Go to GitHub App settings 2. Note App ID (top of page) 3. Generate new private key (scroll down → "Generate a private key") 4. Download .pem file 5. Convert to single line:

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' downloaded-key.pem

6. Copy output and add to .env.local:

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpA...\n-----END RSA PRIVATE KEY-----\n"

Issue 4: Webhooks Not Receiving Events¶

Cause: Webhook URL not accessible from internet

Fix for Local Development: 1. Install ngrok: brew install ngrok (macOS) or download from ngrok.com 2. Start ngrok:

ngrok http 3000

3. Copy https://xxxx-xx-xx-xx.ngrok.io URL 4. Update GitHub App webhook URL to https://xxxx.ngrok.io/api/github/webhook 5. Restart server

Note: Free ngrok URLs change each time you restart. For persistent URL, use paid ngrok or deploy to production.

Issue 5: Database Connection Error¶

Cause: Invalid DATABASE_URL or Neon database not accessible

Fix: 1. Go to Neon Console 2. Copy connection string (should start with postgresql://) 3. Update .env.local:

DATABASE_URL=postgresql://user:password@host.neon.tech/dbname?sslmode=require

4. Test connection:

psql $DATABASE_URL -c "SELECT 1;"

Next Steps After Manual Testing¶

Once all tests pass:

Mark Day 4 as Complete ✅
Move to Day 5: User-Team Auto-Linking
Update NextAuth callback to find user's teams
Implement smart redirect logic
Create /teams page
Optional: Run integration tests
```
npm test installation-handler.test.ts
```

Manual Testing Report Template¶

After testing, document your results:

## Manual Testing Report - GitHub App Installation Flow
**Date**: November X, 2025
**Tester**: Your Name

### Test Environment
- Server: Local development (npm run dev)
- Database: Neon (production)
- GitHub Account: @your-username
- Test Repository: codeslick-test

### Test Results

#### ✅ Installation Flow
- Installation ID: 12345678
- Team Created: team_abc123
- Team Name: your-username's Team
- Team Slug: your-username-x7k9
- Redirect: Success → /teams/team_abc123?welcome=true

#### ✅ Database Records
- Teams table: Record created ✅
- GitHub Installations table: Record created ✅
- Installation linked to team: ✅

#### ✅ Uninstall/Reinstall
- Uninstall webhook received: ✅
- Soft delete (team_id → NULL): ✅
- Reinstall finds existing team: ✅
- No duplicate teams created: ✅

#### ✅ Repository Changes
- Added repo2, repo3: ✅
- Database updated with new repos: ✅

#### ✅ Error Handling
- Feature flag check: ✅
- Missing credentials: ✅
- Invalid installation ID: ✅

### Issues Found
None / [List any issues]

### Recommendations
None / [List any recommendations]

### Conclusion
Installation flow working as expected. Ready for Day 5.

Estimated Time: 30-45 minutes for complete testing

Required Tools: - Browser (Chrome/Firefox) - Terminal - Access to Neon Console or psql - (Optional) ngrok for webhook testing

Support: If you encounter issues, check the server logs first. Most issues are configuration-related (missing env vars).