One Machine, Multiple GitHub Identities: A Team-Friendly SSH Configuration Guide

In today's world of remote work and side projects, many developers find themselves using the same machine for both company work and personal coding. This often leads to a common challenge: how do you manage different GitHub (or other Git service) identities seamlessly and securely? Committing to a work repository with your personal account, or vice-versa, can lead to confusion, failed pushes, or even policy violations.

This guide provides a robust, team-friendly solution using SSH and Git's configuration. It allows you to set a "default" account (e.g., personal) and automatically use your work account for specific repositories, all without requiring any changes that would affect your teammates' workflows.

The Goal:

• Default to Personal: By default, any git command to github.com will use your personal SSH key.
• Automatic Work Profile: When interacting with your company's repositories, Git will automatically use your work SSH key.
• Team-Friendly: The entire solution is configured on your local machine. You won't commit any changes (like modified remote URLs in submodules) that force your teammates to adopt your custom setup.

Step 1: Create Separate SSH Keys for Each Account

First, ensure you have a unique SSH key for each GitHub account.

We'll use the modern and recommended Ed25519 algorithm.

Open your terminal and run these commands, replacing the email and filenames as needed. The -f flag is crucial to specify a unique filename and avoid overwriting existing keys.

Generate a personal key: If you don't have a default SSH key yet, you can accept the default path (~/.ssh/id_ed25519) for your personal key. If you already have one, or want to be explicit:

ssh-keygen -t ed25519 -C "your_personal@email.com" -f ~/.ssh/id_ed25519_personal        

Generate a work key:

ssh-keygen -t ed25519 -C "your_work@email.com" -f ~/.ssh/id_ed25519_work        

When prompted for a passphrase, it's highly recommended to enter a strong one for each key.

Add the public keys to your GitHub accounts:

1. Copy your personal public key content (e.g., cat ~/.ssh/id_ed25519_personal.pub then copy the output) and add it to your personal GitHub account's Settings > SSH and GPG keys as an Authentication Key.
2. Copy your work public key content (e.g., cat ~/.ssh/id_ed25519_work.pub) and add it to your work GitHub account's settings.

Step 2: Configure SSH to Use Your Keys

The magic happens in the SSH configuration file, typically located at ~/.ssh/config. This file tells your SSH client which private key to use when connecting to a specific server address (a "Host").

Create or open ~/.ssh/config with a text editor and add the following configuration:

# Personal GitHub account (DEFAULT)
# This block is for the standard github.com host
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal # <-- Path to your PERSONAL key
    IdentitiesOnly yes
    AddKeysToAgent yes # Optional: Adds key to ssh-agent automatically if it's running

# Work GitHub account (SPECIAL CASE)
# We invent a custom host "github-work" to use for work repos.
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work   # <-- Path to your WORK key
    IdentitiesOnly yes
    AddKeysToAgent yes # Optional        

• Host github.com: This matches the standard GitHub URL, so we configure it to use your personal key by default.
• Host github-work: This is a custom alias (a "nickname") we've just invented. It also points to github.com but will be configured to use our work key.
• HostName github.com: The actual server address SSH will connect to.
• User git: The default user for Git SSH connections.
• IdentityFile: Specifies which private SSH key to use for this host entry.
• IdentitiesOnly yes: Crucially, this tells SSH to only try the specified IdentityFile for this host, preventing it from trying all known keys, which can lead to authentication failures if your GitHub account has a limit on failed attempts or if the wrong key is offered first.
• AddKeysToAgent yes: If you use ssh-agent, this attempts to add the key to the agent when first used, so you don't have to re-enter the passphrase repeatedly (if you set one).

Step 3: Tell Git to Rewrite URLs Automatically (The Team-Friendly Part)

You could manually change your work repository remote URLs from git@github.com:YourWorkOrg/project.git to git@github-work:YourWorkOrg/project.git. However, if you commit this change (e.g., in a .gitmodules file for submodules), it will break the setup for your teammates, as their machines don't know what github-work means.

The elegant and team-friendly solution is to tell your local Git installation to rewrite these URLs on the fly, without altering the repository's actual configuration files that get committed.

Run this global Git configuration command in your terminal, replacing YourWorkOrg with your company's actual GitHub organization name (or your work username if it's a personal work repo under your work account but not in an org):

git config --global url."git@github-work:YourWorkOrg/".insteadOf "git@github.com:YourWorkOrg/"        

If your work repositories are not under a specific organization but directly under your work username, the command would be:

git config --global url."git@github-work:YourWorkUsername/".insteadOf "git@github.com:YourWorkUsername/"        

This command adds a section to your global ~/.gitconfig file. It instructs Git: "For this machine only, any time you encounter an SSH URL for a repository under YourWorkOrg (or YourWorkUsername) that uses github.com, silently replace the github.com part with our special github-work alias before attempting the SSH connection."

How It All Works Together

Now, when you run a command like git pull or git push in a work repository (e.g., one cloned from git@github.com:YourWorkOrg/project.git):

1. Git sees the remote URL, for example, git@github.com:YourWorkOrg/project.git.
2. Your global insteadOf rule in ~/.gitconfig matches the git@github.com:YourWorkOrg/ prefix.
3. Git transparently rewrites the URL in memory to git@github-work:YourWorkOrg/project.git for this operation.
4. Git passes this modified URL (git@github-work:...) to the SSH client.
5. The SSH client sees the host github-work and looks up its configuration in ~/.ssh/config.
6. It finds the Host github-work block and correctly selects your work SSH key (~/.ssh/id_ed25519_work).
7. The connection to GitHub authenticates successfully using your work identity.

Your teammates' machines don't have this local insteadOf rule or the github-work SSH host alias, so they connect to the standard git@github.com:YourWorkOrg/project.git URL using their own default SSH key setup, as they always have. No conflicts, no shared pain!

Verification

You can test that your SSH configuration is correctly identifying keys for each host alias:

# This should connect using your PERSONAL key
ssh -T git@github.com        

Expected output will include something like: Hi YourPersonalUsername! You've successfully authenticated...

# This should connect using your WORK key
ssh -T git@github-work        

Expected output will include something like:

Hi YourWorkUsername! You've successfully authenticated...

If both commands give you the expected "Hi [CorrectUsername]!" messages, you're all set! You now have a powerful, flexible, and team-friendly system for managing multiple GitHub identities on the same machine.

Remember to replace placeholders like your_personal@email.com, YourWorkOrg, etc., with actual values.