How to Use Multiple SSH Keys on GitHub: A Complete Configuration Guide to Manage Multiple Accounts

If you’ve ever juggled multiple GitHub accounts (e.g., a personal account for side projects and a work account for professional repositories), you’ve likely encountered the frustration of SSH key conflicts. By default, Git uses a single SSH key pair (id_rsa/id_rsa.pub) to authenticate with GitHub, which breaks when you try to use two accounts.

This guide will walk you through configuring multiple SSH keys to seamlessly manage multiple GitHub accounts on a single machine. We’ll cover generating unique keys, organizing them, configuring SSH to use the right key for each account, and troubleshooting common issues. By the end, you’ll push/pull code to different GitHub accounts without switching keys manually.

Table of Contents#

  1. Prerequisites
  2. Why Multiple SSH Keys?
  3. Step 1: Generate Unique SSH Keys for Each Account
  4. Step 2: Add SSH Keys to the SSH Agent
  5. Step 3: Configure the SSH Config File
  6. Step 4: Add Public Keys to GitHub Accounts
  7. Step 5: Test the SSH Connection
  8. Step 6: Clone Repositories with the Correct Account
  9. Troubleshooting Common Issues
  10. Conclusion
  11. References

Prerequisites#

Before starting, ensure you have:

  • A computer running macOS, Linux, or Windows (with WSL or Git Bash).
  • Git installed (download here).
  • Two or more GitHub accounts (e.g., personal-user and work-user).
  • Basic familiarity with the command line.

Why Multiple SSH Keys?#

GitHub associates SSH keys with user accounts, not repositories. If you use one key for two accounts, GitHub will reject actions (like git push) because it can’t distinguish which account to use. Multiple SSH keys solve this by:

  • Letting you map specific keys to specific GitHub accounts.
  • Avoiding password prompts (if keys are passphrase-protected, you’ll enter the passphrase once per session).
  • Enhancing security (revoke a key for one account without affecting others).

Step 1: Generate Unique SSH Keys for Each Account#

First, generate a separate SSH key pair for each GitHub account. We’ll use descriptive filenames to avoid overwriting the default id_rsa key (if it exists).

1.1 Navigate to the SSH Directory#

Open your terminal and go to the .ssh folder (create it if it doesn’t exist):

mkdir -p ~/.ssh && cd ~/.ssh

1.2 Generate SSH Keys#

Use ssh-keygen to generate keys. Replace personal and work with labels for your accounts (e.g., github-personal, github-work).

For Personal Account:#

ssh-keygen -t ed25519 -C "[email protected]" -f "id_ed25519_personal"

For Work Account:#

ssh-keygen -t ed25519 -C "[email protected]" -f "id_ed25519_work"

Explanation of flags:

  • -t ed25519: Uses the Ed25519 algorithm (more secure than RSA).
  • -C "email": Adds a comment to identify the key (use your GitHub account email).
  • -f "filename": Specifies the output file (avoids overwriting the default id_rsa).

When prompted, enter a passphrase for added security. You’ll only need to enter it once per session (thanks to the SSH agent, covered next).

Step 2: Add SSH Keys to the SSH Agent#

The SSH agent manages your private keys, so you don’t have to re-enter passphrases every time you use a key.

2.1 Start the SSH Agent#

Ensure the agent is running:

eval "$(ssh-agent -s)"

Output: Agent pid XXXX (success).

2.2 Add Keys to the Agent#

Add your private keys to the agent. Replace id_ed25519_personal and id_ed25519_work with your key filenames:

ssh-add ~/.ssh/id_ed25519_personal
ssh-add ~/.ssh/id_ed25519_work

Optional: Auto-Add Keys on Startup
To avoid re-adding keys after reboot, configure the agent to load them automatically. Edit (or create) ~/.ssh/config (we’ll do this in Step 3) and add AddKeysToAgent yes (see Step 3.2 for details).

Step 3: Configure the SSH Config File#

The ~/.ssh/config file tells SSH which key to use for which GitHub account. This is the most critical step!

3.1 Create/Edit the Config File#

Open the config file in a text editor (e.g., nano, vim, or VS Code):

nano ~/.ssh/config

3.2 Add Account-Specific Rules#

Paste the following, replacing placeholders with your details:

# Personal GitHub Account
Host github.com-personal  # Alias to use in Git commands (e.g., [email protected])
  HostName github.com     # Actual GitHub domain
  User git                # GitHub always uses "git" as the user
  IdentityFile ~/.ssh/id_ed25519_personal  # Path to your personal private key
  AddKeysToAgent yes      # Auto-add key to agent (optional)
  UseKeychain yes         # Store passphrase in keychain (macOS only)
 
# Work GitHub Account
Host github.com-work      # Alias for work account
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  AddKeysToAgent yes
  UseKeychain yes         # Omit on Linux/WSL (use `ssh-askpass` instead)

Key Parameters Explained:

  • Host: The alias you’ll use (e.g., github.com-personal).
  • HostName: The actual server (always github.com for GitHub).
  • IdentityFile: Path to the private key for the account.
  • AddKeysToAgent yes: Automatically adds the key to the agent when used.
  • UseKeychain yes (macOS): Stores the passphrase in the macOS Keychain (no repeated prompts).

3.3 Save and Close the File#

In nano, press Ctrl+O to save, Enter to confirm the filename, then Ctrl+X to exit.

3.4 Set File Permissions#

SSH is strict about permissions. Ensure the config and keys are secure:

chmod 600 ~/.ssh/config  # Read/write for you only
chmod 600 ~/.ssh/id_ed25519_*  # Private keys (600 = read/write for owner)
chmod 644 ~/.ssh/id_ed25519_*.pub  # Public keys (644 = read for all)
chmod 700 ~/.ssh  # Directory (700 = read/write/execute for owner only)

Step 4: Add Public Keys to GitHub Accounts#

Now, add each public key to its corresponding GitHub account.

4.1 Copy the Public Key#

For your personal account, copy the public key (replace id_ed25519_personal.pub with your filename):

cat ~/.ssh/id_ed25519_personal.pub | pbcopy  # macOS
# OR (Linux/WSL)
cat ~/.ssh/id_ed25519_personal.pub | xclip -selection clipboard

4.2 Add Key to GitHub#

  1. Go to GitHub > Settings > SSH and GPG keys.
  2. Click New SSH key.
  3. Add a title (e.g., "Laptop - Personal").
  4. Paste the copied public key into the "Key" field.
  5. Click Add SSH key.

4.3 Repeat for Work Account#

Repeat Steps 4.1–4.2 with your work public key (id_ed25519_work.pub) and work GitHub account.

Step 5: Test the SSH Connection#

Verify that SSH uses the correct key for each account.

Test Personal Account:#

ssh -T [email protected]

Expected Output:

Hi personal-username! You've successfully authenticated, but GitHub does not provide shell access.

Test Work Account:#

ssh -T [email protected]

Expected Output:

Hi work-username! You've successfully authenticated, but GitHub does not provide shell access.

If you see "Permission denied (publickey)", check:

  • The public key was added to the correct GitHub account.
  • The IdentityFile path in ~/.ssh/config is correct.
  • Key permissions (Step 3.4).

Step 6: Clone Repositories with the Correct Account#

To use your new setup, clone repositories using the Host alias from your SSH config.

Example: Clone a Personal Repo#

git clone [email protected]:personal-username/your-repo.git

Example: Clone a Work Repo#

git clone [email protected]:work-username/team-repo.git

Update Existing Repositories#

If you already cloned a repo with the default [email protected] URL, update its remote URL to use your alias:

# For a personal repo
git remote set-url origin [email protected]:personal-username/your-repo.git
 
# Verify the remote
git remote -v

Troubleshooting Common Issues#

Issue 1: "Bad configuration option: AddKeysToAgent"#

Fix: Ensure your SSH version supports AddKeysToAgent (SSH 7.2+). On older systems, omit this line and manually add keys with ssh-add.

Issue 2: "Permission denied (publickey)"#

Check:

  • Run ssh -vT [email protected] for verbose output (look for "Offering public key" to see if your key is used).
  • Ensure ~/.ssh permissions are 700, config is 600, and keys are 600.

Issue 3: Passphrase Prompted Every Time#

Fix: Use ssh-add to add the key to the agent (it will remember the passphrase for your session). On macOS, UseKeychain yes in ~/.ssh/config stores it permanently.

Conclusion#

You’ve now configured multiple SSH keys to manage multiple GitHub accounts! This setup lets you seamlessly switch between accounts without password prompts (after the initial passphrase). Remember to:

  • Use descriptive key filenames.
  • Secure keys with passphrases.
  • Keep ~/.ssh permissions strict.

For advanced use cases (e.g., more than two accounts), repeat the steps with new key filenames and Host aliases in ~/.ssh/config.

References#

2025-12