github-username-to-emails

Usage

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

CLI

npx github-username-to-emails joshuakgoldberg

Account email: [email protected]
Event Email(s): 12
 - [email protected], 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: '[email protected]',
  events: { '[email protected]': [ '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.

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

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