Managing Multiple GitHub SSH Keys

Like most developers in a service organization, I've run right into the classic headache of managing multiple GitHub SSH keys after being reassigned to a new project. It's an incredibly common problem with a simple solution, yet the sheer volume of confusing articles online made it surprisingly difficult to organize the setup and trying to put something may be useful for struggling hands like me.

🖥️ Step 1: Separate Key Generation and Naming 

Generate distinct SSH key pairs for your each work accounts. When generating the keys, use the -flag to specify a unique filename and path.

# Generate work key 1
ssh-keygen -t ed25519 -C "work_1_email@company.com" -f ~/.ssh/id_rsa_work_1

# Generate work key 2
ssh-keygen -t ed25519 -C "work_2_email@company.com" -f ~/.ssh/id_rsa_work_1        

This avoids overwriting the default ~/.ssh/id_rsa file. You should now have at least these files in your ~/.ssh/ directory:

id_rsa_work_1 (private key) and id_rsa_work_1.pub (public key)
id_rsa_work_2 (private key) and id_rsa_work_2.pub (public key)        

🎛️ Step 2: Configure SSH for Specific Hosts 

The ~/.ssh/config file allows you to define different settings for different remote hosts. This is where you tell SSH which private key to use for which domain or alias.

Create or open your ~/.ssh/config file and add the following.

Host work1

    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_work_1
    IdentitiesOnly yes

Host work2

    hostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa_work_2
    IdentitiesOnly yes        

🚴 Step 3: Using the SSH Agent

The SSH agent securely holds your private keys in memory so you don't have to enter the passphrase every time you connect.

1. Start the Agent (if not running):

Most modern systems (like macOS and recent Linux distributions) start the agent automatically.

Run below command

eval "$(ssh-agent -s)"        

1. Add Your Keys:

Add both the keys to the agent. You'll be prompted for the passphrase for each key if one was set during generation.

ssh-add ~/.ssh/id_rsa_work_1

ssh-add ~/.ssh/id_rsa_work_2        

🌍 Step 4: Set your global identity

Before you start committing, it’s good to tell Git who you are (so your commits don’t show up as “Unknown Author”). In your terminal, run:

git config --global user.name "Your Name"
git config --global user.email "you@work.com"        

Replace Your Name and you@work.com with your real name and email. These settings apply globally across all your repos (unless overridden). (Atlassian)

📝 Step 5: Locate & open your .gitconfig file

• On macOS or Linux, it’s usually ~/.gitconfig in your home directory. (Stack Overflow)
• On Windows: C:\Users\<YourUser>\.gitconfig (or wherever your home folder is) (Stack Overflow)
• To open it in your favorite editor, you might run something like:

🔍 Step 6: What you’ll find (and might want to tweak)

Inside .gitconfig you’ll see things like:

[user]
    name = Your Name
    email = you@work.com
[core]
    editor = code –wait        

And you may add or change Your preferred text editor via [core] editor (so Git uses your editor when it needs you to type messages).

🛠️ Step 7: Setting up Folder-Specific .gitconfig Files

The next step is to organize your cloned repositories in a way that works best for you either by project name, client name, or whatever system you prefer. For example, I've created two folders named work_1 and work_2 to keep things tidy. Once this is completed we will configure gitconfig for each folders we have created.

1. Create folder-specific Git config files

Create separate config files in your home directory (or any location you prefer). For example:

touch ~/.gitconfig_work_1

touch ~/.gitconfig_work_2        

Inside each of these files, put the identity or settings you want. Example:

~/.gitconfig_work_1

[user]
    name = Your Name 
    email = you@work_1.com        

~/.gitconfig_work_2

[user]
    name = Your Name 
    email = you@work_2.com        

2. Update your global .gitconfig file

Edit your ~/.gitconfig file to include the folder-based configs using includeIf. Add something like:

[includeIf "gitdir:~/Projects/work_1/"]

  path = .gitconfig_work_1

[includeIf "gitdir:~/Projects/work_2/"]

  path = .gitconfig_work_2        

After adding it your global config file will look like below

[user]

    email = you@work_email.com // Global configuration
    name = Your Name  // Global configuration 

[core]

    editor = code --wait
    autocrlf = true

[includeIf "gitdir:~/Projects/work_1/"]

  path = .gitconfig_work_1

[includeIf "gitdir:~/Projects/work_2/"]

  path = .gitconfig_work_2        

✅ Make sure the folder path ends with a slash (/) so Git matches it properly as a directory.

3. Verify your config is working

Navigate into one of the folders and check the Git config:

cd ~/Projects/work_1/my-repo        

git config user.name        

# Should return: Your Name           

git config user.email        

# Should return: you@work_1.com        

🚧 Notes:

• Git will use the most specific matching config file, falling back to global if needed.
• You can override more than just user name/email (e.g., signing key, diff settings, etc.)
• Make sure the paths in includeIf are correct — ~ may not always expand as expected; if it doesn't work, use the full path like /home/yourname/Projects/....