_ _                       _ _ 
  __ _(_) |_ ___ _ __ ___   __ _(_) |
 / _` | | __/ _ \ '_ ` _ \ / _` | | |
| (_| | | ||  __/ | | | | | (_| | | |
 \__, |_|\__\___|_| |_| |_|\__,_|_|_|
 |___/                               

Generate a social network of names and email adresses based on github usernames. It is first a CLI application that finds collaborators, followers, and commiters, but it also supports a fully localized web GUI dashboard to visualize the connections.

Installation

Requirements:

• Python 3.8 or newer (uses only the standard library)

git clone https://github.com/magnus530/gitemail.git
cd gitemail
chmod +x gitemail.py

Terminal usage:

python3 gitemail.py username

Run with your own github API key with the --token flag to increase API rate (60→5000 req/hr).

ex.) python3 gitemail.py --token YOUR_TOKEN_HERE username

python3 gitemail.py --help

Default caps (--max-users 50, --max-repos 10, --max-prs 10) to avoid API rate limit.

usage: gitemail.py [-h] [--token TOKEN] [--depth DEPTH] [--max-users MAX_USERS] [--max-repos MAX_REPOS] [--max-commits MAX_COMMITS] [--max-prs MAX_PRS] [--max-followers MAX_FOLLOWERS] [--no-followers] [--no-collaborators] [--no-prs] [--include-noreply] [--json] [-q] username

GitHub social-graph + email harvester. BFS from a seed username, harvest emails on each user reached.

positional arguments: username Seed GitHub username

options: -h, --help show this help message and exit --token TOKEN GitHub PAT (or GITHUB_TOKEN env) --depth DEPTH BFS depth (default 1; 0 = seed only) --max-users MAX_USERS Hard cap on graph size (default 50) --max-repos MAX_REPOS Repos scanned per user (default 10) --max-commits MAX_COMMITS Commits per repo (default 30) --max-prs MAX_PRS PRs per repo (default 10) --max-followers MAX_FOLLOWERS Followers/following per user (default 50) --no-followers --no-collaborators --no-prs --include-noreply Include @users.noreply.github.com --json Output graph JSON -q, --quiet Suppress progress on stderr

Discovery sources (per user): profile email GET /users/{u} push events GET /users/{u}/events/public (PushEvent commit emails) owned repo commits GET /repos/{r}/commits?author={u} (author/committer + co-author trailers) contributors GET /repos/{r}/contributors collaborators GET /repos/{r}/collaborators (often 403 unless admin) PR authors / reviewers GET /repos/{r}/pulls?state=all followers / following GET /users/{u}/followers, /following

BFS: depth 0 seed user only, no graph (just emails) depth 1 seed + immediate neighbors (default) depth 2 + neighbors-of-neighbors (warning: API-heavy, even with a token)

Rate limits: unauthenticated 60 req/hr with token 5000 req/hr (export GITHUB_TOKEN=ghp_...) search endpoints and secondary limits apply separately

Examples:

seed-only email dump (no graph traversal)

gitemail.py torvalds --depth 0

1-hop social graph, text output

GITHUB_TOKEN=ghp_xxx gitemail.py defunkt

1-hop graph as JSON for Gephi/Cytoscape, drop noisy follower edges

GITHUB_TOKEN=ghp_xxx gitemail.py defunkt --no-followers --json > graph.json

2-hop, capped tight to stay inside the rate budget

GITHUB_TOKEN=ghp_xxx gitemail.py defunkt
--depth 2 --max-users 100 --max-repos 5 --max-prs 5
--no-collaborators --no-followers -q --json > graph.json

include @users.noreply.github.com (filtered by default)

gitemail.py defunkt --include-noreply

Output (text mode):

• (d0) seed user, marked with * (d1) discovered at depth 1 harvested email [coauthor] co-author trailer (orphan, no login resolved)

Output (--json): {"nodes": [{login, name, depth, emails:[{email,names,sources}], coauthor_emails:[...]}], "edges": [{source, target, type, evidence}]}

Edge types: commit_author, commit_committer, contributor, collaborator, pr_author, pr_reviewer, follows