GitHub Auth

Note: Create separate GitHub OAuth Apps for local and production environments. Repeat this for any additional staging or preview environments to ensure isolation.

1. Create a GitHub OAuth App

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App (or visit github.com/settings/developers)
2. Fill in:
   • Application name — your app name
   • Homepage URL — http://localhost:3000 (dev) or https://yourdomain.com (prod)
   • Authorization callback URL:
     • http://localhost:3000/api/auth/callback/github (dev)
     • https://yourdomain.com/api/auth/callback/github (prod)
3. Click Register application
4. Copy the Client ID and generate a Client Secret

2. Set Environment Variables

# .env.local
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

3. Enable in Config

In src/appConfig.ts set:

github: { enabled: true },

4. Test

1. Run pnpm dev
2. Navigate to /auth/sign-in
3. A Sign in with GitHub button will appear

Production Checklist

• Update the Authorization callback URL in the GitHub OAuth App settings to your production domain
• Make sure the Email Addresses permission is set to Read-only if using a GitHub App

Troubleshooting

• email_not_found — you created a GitHub App without the Email Addresses read permission, or the user's primary email is set to private. See GitHub docs on user emails
• No GitHub button — check GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set and github.enabled is true in appConfig.ts