GitHub

HOW in lib/github.py. Sourcing-relevant subset only; index: reference/docs/github/raw/endpoints.md.

Auth & config

• REST: https://api.github.com · GraphQL: https://api.github.com/graphql.
• Auth: PAT (fine-grained or classic) → Authorization: Bearer <token> (env GITHUB_TOKEN; never hardcode) + X-GitHub-Api-Version: 2022-11-28.
• Rate limits: REST 5,000/hr · Search 30 req/min, 1,000-result cap · GraphQL ~5,000 points/hr. Search pagination: page/per_page (≤100); iter_search_users respects the cap. Adapter auto-sleeps on 403/429 rate-limit + transient 5xx.

Operations

Discovery: search_users/iter_search_users, search_repositories, search_code. Profile + skill signal: get_user, list_user_repos, get_repo_contributors, list_user_followers. Ops: get_rate_limit. graphql(query, variables) — generic passthrough (one endpoint; you specify the fields) for rich single-call dossiers: profile + socialAccounts (linked LinkedIn/Twitter) + top languages + pinned repos + contributionsCollection.

Pulling contact details when they ARE listed/derivable

GitHub does expose contact info three ways — try these before falling back to the waterfall:

1. Public profile email + site + twitter: get_user(username) → email (if the dev set one public), blog, twitter_username, bio.
2. LinkedIn / social links (the icons under the avatar): get_user_social_accounts(username) → [{provider, url}] (linkedin, mastodon, …). Also in GraphQL user.socialAccounts.
3. Commit-email harvest (when the profile email is private): find_user_emails(username) walks their recent owned repos' commits and returns real emails, dropping *@users.noreply.github.com proxies. (Primitives: list_repo_commits(author=…), list_user_events.)

⚠️ The recruiter reality

• Even with the above, many devs have no usable email on GitHub (private email + noreply commits). So GitHub is still primarily discovery + skill signal → if 1–3 come up empty, hand name + company + GitHub/LinkedIn to the enrichment waterfall. GitHub slots in before enrichment.
• Run narrow search queries (rate cap; find_user_emails is bounded by max_repos). Keep outreach human-paced (ToS).

Handoff (IT candidate sourcing)

search_users/get_repo_contributors by language+location → get_user+list_user_repos (skill signal) → score vs the JD (agent, free) → enrich email (waterfall) → validate → ATS (Vincere/Bullhorn) → sequencer (SourceWhale/Lemlist/HeyReach). The engineer-sourcing front-end for the "source & shortlist" recipe.

Callable surface — lib/github.py

Import: from lib.github import GitHub → instantiate GitHub() (reads key from env). Base: https://api.github.com. Generic passthrough: request(method, path, *, params, json).

• candidate_dossier(full_name: str | None = None, *, github_url: str | None = None, company_name: str | None = None, location: str | None = None, linkedin_url: str | None = None, jd_keywords: list[str] | str | None = None, max_candidates: int = 5, max_repos: int = 12, include_emails: bool = True) -> dict[str, Any] — End-to-end IT-sourcing GitHub leg: match identity → build dossier → score repos vs JD.
• find_user_emails(username: str, *, max_repos: int = 10) -> list[str] — Harvest candidate emails from a user's public commits (when the profile email is private).
• get_rate_limit() -> Any — GET /rate_limit — remaining REST/Search/GraphQL budget for the caller's own GitHub token; requires the workspace's own token.
• get_repo_contributors(owner: str, repo: str, **params) -> Any — GET /repos/{owner}/{repo}/contributors — source the people who build a given project.
• get_repo_tree(owner: str, repo: str, *, ref: str = 'HEAD', recursive: bool = True) -> Any — GET /repos/{owner}/{repo}/git/trees/{ref} — list every path in the repo in one call.
• get_user(username: str) -> Any — GET /users/{username} — profile: name, company, location, blog, email (if public), hireable, counts.
• get_user_social_accounts(username: str) -> Any — GET /users/{username}/social_accounts — the linked social accounts shown on the profile (e.g. LinkedIn, Mastodon, Twitter): list of {provider, url}. This is where a profile's LinkedIn lives.
• graphql(query: str, variables: dict | None = None) -> Any — POST /graphql — run any GraphQL query/mutation. Best for rich single-call candidate dossiers (profile + socialAccounts + top languages + pinned repos + contributions in one round-trip).
• iter_search_users(q: str, *, per_page: int = 100, max_results: int = 1000, **params) -> Iterator[dict] — Paginate /search/users up to GitHub's 1,000-result cap.
• list_repo_commits(owner: str, repo: str, *, author: str | None = None, per_page: int = 100, **params) -> Any — GET /repos/{owner}/{repo}/commits — commits (filter by author=username). Each carries commit.author.email / commit.committer.email — the basis for commit-email harvesting.
• list_user_events(username: str, **params) -> Any — GET /users/{username}/events/public — public activity (PushEvents carry commit author emails).
• list_user_followers(username: str, **params) -> Any — GET /users/{username}/followers — network expansion.
• list_user_repos(username: str, *, sort: str = 'pushed', per_page: int = 100, **params) -> Any — GET /users/{username}/repos — skill signal: languages, stars, recency. sort: pushed|updated|created|full_name.
• read_file(owner: str, repo: str, path: str, *, ref: str | None = None) -> Any — GET /repos/{owner}/{repo}/contents/{path} — read one file, authenticated + decoded.
• search_code(q: str, *, per_page: int = 30, page: int = 1, **params) -> Any — GET /search/code — find code (derive authors using a specific tech). Stricter rate limit.
• search_profile_match(full_name: str, *, company_name: str | None = None, location: str | None = None, linkedin_url: str | None = None, max_candidates: int = 5) -> dict[str, Any] — Name → likely GitHub identity matches with confidence scoring.
• search_repositories(q: str, *, sort: str | None = None, order: str | None = None, per_page: int = 30, page: int = 1) -> Any — GET /search/repositories — q e.g. 'language:rust stars:>500 topic:cli'. sort: stars|forks|updated.
• search_users(q: str, *, sort: str | None = None, order: str | None = None, per_page: int = 30, page: int = 1) -> Any — GET /search/users — find developers. q e.g. 'location:Berlin language:Go followers:>50 repos:>10'.
• user_dossier(username: str, *, jd_keywords: list[str] | str | None = None, max_repos: int = 12, include_emails: bool = True) -> dict[str, Any] — Return a recruiter-ready GitHub dossier for one user.