Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as opaque submodule gitlinks on GitHub) into fully-tracked first-party content. AITM now merges its 7 vendored repos as first-party engines: - memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts - git: vendored C git (bundled binary) + gitnexus (in-process code intelligence) - agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess) Includes the full session's product build: Gitgram web/mobile/backend features, AITM website/CLI/MCP, the unified memory layer, engine build tooling (scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md), and extensive test suites. Build artifacts, node_modules, external/, and gemini-cli are gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5.2 KiB
5.2 KiB
OAuth Provider Setup Guide
This guide explains how to enable GitHub and Google OAuth login for Gitgram TimeMachine using Clerk.
Prerequisites
- Clerk account with application created
- Access to Clerk Dashboard
- (For production) OAuth app credentials from GitHub and Google
1. GitHub OAuth Setup
Step 1: Create GitHub OAuth App
- Go to GitHub Developer Settings
- Click "New OAuth App"
- Fill in the details:
- Application name:
Gitgram TimeMachine - Homepage URL:
https://timemachine.gitgram.app(or your domain) - Authorization callback URL:
https://clerk.gitgram.app/v1/oauth_callback- For development:
https://YOUR_CLERK_FRONTEND_API/v1/oauth_callback
- For development:
- Application name:
- Click "Register application"
- Copy the Client ID
- Generate and copy a Client Secret
Step 2: Configure in Clerk
- Go to Clerk Dashboard
- Select your application
- Navigate to User & Authentication → Social Connections
- Find GitHub and click Configure
- Enter:
- Client ID: From GitHub OAuth App
- Client Secret: From GitHub OAuth App
- Enable the connection
- (Optional) Select which scopes to request:
read:user- Basic profile informationuser:email- Email addressesread:org- Organization membership (for team features)
Step 3: Test
- Visit your application's sign-in page
- Click "Continue with GitHub"
- Authorize the application
- Verify successful login
2. Google OAuth Setup
Step 1: Create Google OAuth Credentials
- Go to Google Cloud Console
- Create a new project or select existing
- Navigate to APIs & Services → Credentials
- Click "Create Credentials" → "OAuth client ID"
- Configure consent screen if prompted:
- User Type: External (or Internal for Google Workspace)
- App name: Gitgram TimeMachine
- User support email: your email
- Developer contact: your email
- Create OAuth Client:
- Application type: Web application
- Name:
Gitgram TimeMachine Clerk - Authorized redirect URIs:
https://clerk.gitgram.app/v1/oauth_callback- For development:
https://YOUR_CLERK_FRONTEND_API/v1/oauth_callback
- For development:
- Copy Client ID and Client Secret
Step 2: Configure in Clerk
- Go to Clerk Dashboard
- Select your application
- Navigate to User & Authentication → Social Connections
- Find Google and click Configure
- Enter:
- Client ID: From Google Cloud Console
- Client Secret: From Google Cloud Console
- Enable the connection
Step 3: Test
- Visit your application's sign-in page
- Click "Continue with Google"
- Select Google account
- Verify successful login
3. Quick Setup (Development Only)
For development/testing, Clerk provides pre-configured OAuth apps:
- Go to Clerk Dashboard
- Navigate to User & Authentication → Social Connections
- Toggle ON for GitHub and/or Google
- Use "Use Clerk's development credentials" option
Note: Development credentials have rate limits and should not be used in production.
4. Environment Variables
Ensure these are set in your deployment:
# Clerk Configuration
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...
# Frontend URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard
5. Additional OAuth Providers
Clerk supports many OAuth providers. To add more:
- Go to Clerk Dashboard → Social Connections
- Available providers include:
- Microsoft / Azure AD
- Apple
- Discord
- Slack
- Twitter/X
- GitLab
- Bitbucket
- And many more
Each follows a similar pattern:
- Create OAuth app with the provider
- Get Client ID and Secret
- Configure in Clerk Dashboard
- Test the connection
6. Troubleshooting
"Redirect URI mismatch" Error
- Ensure the redirect URI in your OAuth app exactly matches Clerk's callback URL
- Check for trailing slashes
- Verify protocol (https vs http)
"Access Denied" Error
- Verify the OAuth app is published (not in testing mode)
- Check that required scopes are approved
- For Google: Ensure OAuth consent screen is configured
User Not Created
- Check Clerk webhook configuration
- Verify the API server is receiving webhook events
- Check API server logs for errors
7. Security Best Practices
- Rotate secrets regularly - Update OAuth secrets every 90 days
- Use production credentials - Never use development credentials in production
- Limit scopes - Only request the minimum necessary permissions
- Monitor access - Review OAuth app access logs periodically
- Enable 2FA - Require 2FA for accounts with OAuth app management access