GitLeads

GitLeads is an open-source web app for finding relevant GitHub contributors from a natural-language prompt, enriching lead data, and sending outreach through Gmail.

Highlights

• Prompt-based GitHub lead generation
• GitHub OAuth authentication with per-user access token search
• MCP-backed repository discovery (mcp-use + @modelcontextprotocol/server-github)
• Contributor profiling from GitHub users and commit metadata
• Optional Apollo enrichment for additional contact data
• Optional Gemini prompt analysis for better repo/query targeting
• Gmail OAuth + send workflow for outreach
• Admin users dashboard backed by DynamoDB

Product Flow

1. User enters a campaign prompt.
2. App authenticates with GitHub (if not already signed in).
3. Backend builds one or more GitHub repository search queries.
4. Repositories are discovered through MCP, then GitHub REST fallback if needed.
5. Top contributors are collected and enriched into outreach-ready leads.
6. User selects leads and sends email outreach from connected Gmail.

Tech Stack

• Next.js App Router
• TypeScript
• NextAuth (GitHub OAuth)
• MCP (mcp-use, GitHub MCP server)
• GitHub REST API
• Optional Gemini API
• Optional Apollo API
• Gmail OAuth + Gmail API
• Optional DynamoDB persistence for admin analytics

Repository Layout

app/                  Next.js app routes and API routes
components/           Client UI components
lib/                  Campaign, auth, integrations, and helpers
public/               Static assets
scripts/              Deployment and utility scripts
types/                Shared TypeScript declarations

Prerequisites

• Node.js 20+
• npm 10+
• A GitHub OAuth app
• (Optional) Google OAuth app for Gmail outreach
• (Optional) Apollo API key
• (Optional) Gemini API key
• (Optional) AWS credentials + DynamoDB table for /users

Quick Start

1. Install dependencies.

npm install

2. Copy environment template.

cp .env.example .env.local

3. Fill required variables in .env.local.

4. Run local dev server.

npm run dev

5. Open http://localhost:3000.

Environment Variables

Required for core app auth:

Variable	Required	Description
AUTH_SECRET	Yes	Secret used by NextAuth/session crypto
NEXTAUTH_URL	Yes	Base URL for auth callbacks
GITHUB_CLIENT_ID	Yes	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	Yes	GitHub OAuth app client secret

Required only for Gmail outreach:

Variable	Required	Description
GOOGLE_CLIENT_ID	For Gmail	Google OAuth client ID
GOOGLE_CLIENT_SECRET	For Gmail	Google OAuth client secret

Optional integrations:

Variable	Required	Description
APOLLO_API_KEY	No	Enables Apollo enrichment
GEMINI_API_KEY	No	Enables Gemini query analysis
GMAIL_MCP_SERVER_URL	No	Uses external Gmail MCP endpoint before Gmail API fallback

Optional admin dashboard persistence:

Variable	Required	Description
USER_REGISTRY_TABLE	For /users	DynamoDB table name for login analytics
AWS_REGION	For /users	AWS region
AWS_ACCESS_KEY_ID	For /users	AWS access key
AWS_SECRET_ACCESS_KEY	For /users	AWS secret key

Scripts

• npm run dev - start development server
• npm run build - build production bundle
• npm run start - start production server
• npm run lint - run ESLint

API Routes

• POST /api/campaigns/start - generate campaign + leads from prompt
• POST /api/outreach/send - send outreach to selected recipients
• GET /api/gmail/status - read Gmail connection status
• GET /api/gmail/connect - start Gmail OAuth flow
• GET /api/gmail/callback - handle Gmail OAuth callback
• POST /api/gmail/disconnect - clear Gmail connection
• GET /api/admin/users - admin analytics endpoint

Deployment

This app is Vercel-ready.

vercel link
vercel env add
vercel --prod

If you use AWS Secrets Manager, you can sync env vars with:

./scripts/sync-secrets-to-vercel.sh <secret-id> production

Security Notes

• Never commit .env.local or real credentials.
• Use least-privilege OAuth scopes where possible.
• Rotate API keys/tokens if exposed.
• Treat GitHub search limits as a production reliability concern and add backoff/429 handling.

Contributing

1. Fork the repo.
2. Create a feature branch.
3. Make changes with tests/lint passing.
4. Open a pull request with a clear summary and screenshots for UI changes.

License

Choose and add a license file before publishing (MIT is common for this type of project).