gh-setup-git-identity

A tool to setup git identity based on current GitHub user.

Overview

gh-setup-git-identity is a CLI tool that simplifies setting up your git identity using your GitHub account. It automatically fetches your GitHub username and primary email address, then configures git with these values.

Instead of manually running:

printf "y" | gh auth login -h github.com -s repo,workflow,user,read:org,gist --git-protocol https --web
gh auth setup-git -h github.com

USERNAME=$(gh api user --jq '.login')
EMAIL=$(gh api user/emails --jq '.[] | select(.primary==true) | .email')

git config --global user.name "$USERNAME"
git config --global user.email "$EMAIL"

You can simply run:

gh-setup-git-identity

Features

• Automatic identity setup: Fetches username and email from GitHub
• Global and local configuration: Configure git globally or per-repository
• Authentication check: Prompts you to login if not authenticated
• Git credential helper setup: Automatically runs gh auth setup-git to configure git to use GitHub CLI for HTTPS authentication
• Dry-run mode: Preview changes without making them
• Cross-platform: Works on macOS, Linux, and Windows
• Verbose mode: Built-in verbose mode for debugging

Prerequisites

• Bun >= 1.0.0
• Git (installed and configured)
• GitHub CLI (gh) installed

To install Bun, see: https://bun.sh/ To install GitHub CLI, see: https://cli.github.com/

Installation

Global Installation (CLI)

bun install -g gh-setup-git-identity

Local Installation (Library)

bun install gh-setup-git-identity

CLI Usage

Basic Usage

# Setup git identity globally (default)
gh-setup-git-identity

# Setup git identity for current repository only
gh-setup-git-identity --local

# Preview what would be configured (dry run)
gh-setup-git-identity --dry-run

# Verify current git identity configuration
gh-setup-git-identity --verify

# Enable verbose output
gh-setup-git-identity --verbose

CLI Options

Usage: gh-setup-git-identity [options]

Git Identity Options:
  --global, -g         Set git config globally (default: true)
  --local, -l          Set git config locally (in current repository)
  --dry-run, --dry     Dry run - show what would be done without making changes
  --verify             Verify current git identity configuration
  --repair             Repair git identity without triggering login (requires existing auth)
  --no-auto-login      Disable automatic login if not authenticated
  --verbose, -v        Enable verbose output

GitHub Authentication Options:
  --hostname           GitHub hostname to authenticate with (default: github.com)
  --scopes, -s         Authentication scopes, comma-separated (default: repo,workflow,user,read:org,gist)
  --git-protocol, -p   Protocol for git operations: ssh or https (default: https)
  --web, -w            Open a browser to authenticate (default: true)
  --with-token         Read token from standard input
  --skip-ssh-key       Skip generate/upload SSH key prompt
  --insecure-storage   Save credentials in plain text instead of credential store
  --clipboard          Copy one-time OAuth device code to clipboard

General Options:
  --help, -h           Show help
  --version            Show version number

Advanced Authentication Examples

# Authenticate with GitHub Enterprise
gh-setup-git-identity --hostname enterprise.github.com

# Use SSH protocol instead of HTTPS
gh-setup-git-identity --git-protocol ssh

# Authenticate with custom scopes
gh-setup-git-identity --scopes repo,user,gist

# Use token-based authentication (reads from stdin)
echo "ghp_xxxxx" | gh-setup-git-identity --with-token

# Copy OAuth code to clipboard automatically
gh-setup-git-identity --clipboard

# Skip SSH key generation prompt
gh-setup-git-identity --git-protocol ssh --skip-ssh-key

# Store credentials in plain text (not recommended for production)
gh-setup-git-identity --insecure-storage

First Run (Not Authenticated)

If you haven't authenticated with GitHub CLI yet, the tool will automatically start the authentication process:

GitHub CLI is not authenticated. Starting authentication...

Starting GitHub CLI authentication...

! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...

The tool runs gh auth login automatically with the required scopes (repo,workflow,user,read:org,gist), followed by gh auth setup-git to configure git to use GitHub CLI as the credential helper. Follow the browser-based authentication flow to complete login.

If automatic authentication fails, you can run the commands manually:

printf "y" | gh auth login -h github.com -s repo,workflow,user,read:org,gist --git-protocol https --web
gh auth setup-git -h github.com

Successful Run

Fetching GitHub user information...
  GitHub user: your-username
  GitHub email: [email protected]

Configuring git (global)...
  Git identity configured successfully!

  Git configured:
    user.name:  your-username
    user.email: [email protected]
  Scope: global (--global)

Git identity setup complete!

You can verify your configuration with:
  gh auth status
  git config --global user.name
  git config --global user.email

Verifying Configuration

You can verify your git identity configuration at any time using:

gh-setup-git-identity --verify

Or by running the three verification commands directly:

gh auth status
git config --global user.name
git config --global user.email

For local repository configuration, use --local:

gh-setup-git-identity --verify --local

Or:

gh auth status
git config --local user.name
git config --local user.email

Repairing Configuration

If your git identity configuration becomes corrupted or misconfigured (e.g., empty user.name or user.email), you can use the --repair option to fix it without triggering a new login:

# Repair git identity using existing authentication
gh-setup-git-identity --repair

This is useful when:

• Git operations fail with "empty ident name not allowed" error
• The user.name or user.email was accidentally cleared or corrupted
• You want to reconfigure git identity without going through the login flow again

The --repair option requires that you're already authenticated with GitHub CLI. If not authenticated, it will show helpful instructions for manual authentication.

Disabling Auto-Login

By default, if you're not authenticated, the tool will automatically start the GitHub CLI login process. You can disable this behavior:

# Fail immediately if not authenticated (don't auto-login)
gh-setup-git-identity --no-auto-login

This is useful in scripts or automated environments where you want to fail fast rather than wait for an interactive login prompt.

Library Usage

Basic Example

import { setupGitIdentity, isGhAuthenticated } from 'gh-setup-git-identity';

// Check if authenticated first
const authenticated = await isGhAuthenticated();
if (!authenticated) {
  console.log('Please run: gh auth login');
  process.exit(1);
}

// Setup git identity
const result = await setupGitIdentity();
console.log('Configured:', result.username, result.email);

// Setup with options
const result2 = await setupGitIdentity({
  scope: 'local',      // 'global' or 'local'
  dryRun: true,        // Preview only
  verbose: true        // Enable verbose logging
});

API Reference

isGhAuthenticated(options?)

Check if GitHub CLI is authenticated.

Returns: Promise<boolean>

runGhAuthLogin(options?)

Run gh auth login with configurable options.

Parameters:

• options.hostname - GitHub hostname (default: 'github.com')
• options.scopes - OAuth scopes, comma-separated (default: 'repo,workflow,user,read:org,gist')
• options.gitProtocol - Git protocol: 'ssh' or 'https' (default: 'https')
• options.web - Open browser to authenticate (default: true)
• options.withToken - Read token from stdin (default: false)
• options.skipSshKey - Skip SSH key prompt (default: false)
• options.insecureStorage - Store credentials in plain text (default: false)
• options.clipboard - Copy OAuth code to clipboard (default: false)
• options.verbose - Enable verbose logging (default: false)
• options.logger - Custom logger (default: console)

Returns: Promise<boolean> - true if login was successful

runGhAuthSetupGit(options?)

Run gh auth setup-git to configure git to use GitHub CLI as the credential helper.

This is automatically called after gh auth login and also when running gh-setup-git-identity to ensure git is properly configured for HTTPS operations. Without this, git push/pull may fail with "could not read Username" error.

Parameters:

• options.hostname - GitHub hostname (default: 'github.com')
• options.force - Force setup even if the host is not known (default: false)
• options.verbose - Enable verbose logging (default: false)
• options.logger - Custom logger (default: console)

Returns: Promise<boolean> - true if setup was successful

defaultAuthOptions

Default authentication options object that can be imported and used as a reference:

{
  hostname: 'github.com',
  scopes: 'repo,workflow,user,read:org,gist',
  gitProtocol: 'https',
  web: true,
  withToken: false,
  skipSshKey: false,
  insecureStorage: false,
  clipboard: false
}

getGitHubUserInfo(options?)

Get GitHub user information (username and primary email).

Returns: Promise<{username: string, email: string}>

setupGitIdentity(options?)

Setup git identity based on GitHub user.

Parameters:

• options.scope - 'global' or 'local' (default: 'global')
• options.dryRun - Preview only, don't make changes (default: false)
• options.verbose - Enable verbose logging (default: false)
• options.logger - Custom logger (default: console)

Returns: Promise<{username: string, email: string}>

verifyGitIdentity(options?)

Get current git identity configuration.

Returns: Promise<{username: string|null, email: string|null}>

Multi-Environment Usage

Important: GitHub OAuth Token Limits

GitHub limits OAuth tokens to 10 per user/application/scope combination. If you use gh-setup-git-identity on more than 10 machines or environments, the oldest tokens will be automatically revoked by GitHub, causing authentication failures on those machines.

For more details, see the GitHub documentation on token expiration and revocation.

Recommended: Use Personal Access Tokens (PATs)

For multi-environment setups (Docker containers, CI/CD, multiple servers), we recommend using Personal Access Tokens instead of the OAuth device flow:

1. Create a PAT at https://github.com/settings/tokens with these scopes:

   • repo, workflow, user, read:org, gist

2. Authenticate using the token:

# Option 1: Via stdin
echo "ghp_your_token_here" | gh-setup-git-identity --with-token

# Option 2: Via environment variable (recommended for automation)
export GH_TOKEN="ghp_your_token_here"
gh-setup-git-identity

Why PATs Are Better for Multi-Environment

• No token limit: PATs don't count toward the 10-token OAuth limit
• Consistent authentication: Same token works across all environments
• Explicit control: You manage the token lifecycle
• CI/CD friendly: Easy to inject as a secret

Revoking Old OAuth Tokens

If you've accumulated OAuth tokens and need to clean up:

1. Go to GitHub Settings > Applications > Authorized OAuth Apps
2. Find "GitHub CLI" in the list
3. Click Revoke to remove all OAuth tokens
4. Re-authenticate with gh-setup-git-identity

For a detailed case study of this issue, see docs/case-studies/issue-26/.

Configuration

Environment Variables

Git Identity Options

• GH_SETUP_GIT_IDENTITY_GLOBAL - Set global config (default: true)
• GH_SETUP_GIT_IDENTITY_LOCAL - Set local config (default: false)
• GH_SETUP_GIT_IDENTITY_DRY_RUN - Enable dry run mode (default: false)
• GH_SETUP_GIT_IDENTITY_VERBOSE - Enable verbose output (default: false)

GitHub Authentication Options

• GH_AUTH_HOSTNAME - GitHub hostname (default: github.com)
• GH_AUTH_SCOPES - Authentication scopes (default: repo,workflow,user,read:org,gist)
• GH_AUTH_GIT_PROTOCOL - Git protocol: ssh or https (default: https)
• GH_AUTH_WEB - Open browser for authentication (default: true)
• GH_AUTH_SKIP_SSH_KEY - Skip SSH key prompt (default: false)
• GH_AUTH_INSECURE_STORAGE - Store credentials in plain text (default: false)
• GH_AUTH_CLIPBOARD - Copy OAuth code to clipboard (default: false)

Testing

Run tests using bun:

bun test

Development

Project Structure

gh-setup-git-identity/
├── src/
│   ├── index.js          # Core library
│   └── cli.js            # CLI interface
├── test/
│   └── index.test.js     # Tests
├── .changeset/           # Changesets for versioning
├── .github/
│   └── workflows/        # CI/CD workflows
├── package.json
└── README.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This is free and unencumbered software released into the public domain. See LICENSE for details.

Links

• GitHub Repository: https://github.com/link-foundation/gh-setup-git-identity
• Issue Tracker: https://github.com/link-foundation/gh-setup-git-identity/issues
• Link Foundation: https://github.com/link-foundation

Related Projects

• gh-upload-log - Upload log files to GitHub
• lino-arguments - CLI argument parsing
• log-lazy - Efficient lazy evaluation logging
• command-stream - Streamable commands