github-username-to-emails

Fetches any public emails associated with a GitHub username. 📧

Usage

You can run this as a standalone command, or by its Node.js API.

CLI

npx github-username-to-emails joshuakgoldberg

Account email: github@joshuakgoldberg.com
Event Email(s): 12
 - git@joshuakgoldberg.com, with names: Josh Goldberg, Josh Goldberg ✨
 - ...

Node.js

npm i github-username-to-emails

import { getGitHubUsernameEmails } from "github-username-to-emails";

await getGitHubUsernameEmails({ username: "joshuakgoldberg" });

/*
{
  account: 'github@joshuakgoldberg.com',
  events: { 'git@joshuakgoldberg.com': [ 'Josh Goldberg ✨', 'Josh Goldberg' ] }
}
*/

Calling getGitHubUsernameEmails will try to find the user's email from two public data points:

• account: /users/${username}: public account information
• events: /users/{username}/events: commits pushed by the user
  • This is stored as an object containing, under each email, the commit names associated with that email
  • Note that these may be commits originally authored by other users, not the user you're looking for

Note that account might be undefined and events might be {}. Only publicly visible emails can be retrieved.

Options

auth is retrieved with get-github-auth-token, which defaults to process.env.GH_TOKEN, or failing that, gh auth token. If neither is available then an auth token must be provided as an option.

Option	Type	Description	Default
auth	string	Auth token for Octokit REST calls.	process.env.GH_TOKEN or $(gh auth token)
historyLimit	number	How many public events to look at.	500
username	string	GitHub user to check emails of.

await getGitHubUsernameEmails({
	auth: "gho_abc123",
	historyLimit: 9001,
	username: "joshuakgoldberg",
});

Email Privacy

This package doesn't expose any data users aren't already providing to GitHub. You can manually check the same data it looks at on:

1. A user's public GitHub profile
2. https://api.github.com/users/<username>/events

This package only serves as a convenience to same time searching through that data.

To hide your email from public view, see GitHub's Setting your commit email address docs.

Contributors

Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧

💙 This package was templated with create-typescript-app.