Managing Multiple SSH Keys for Git Access

A comprehensive guide for managing different SSH keys across multiple computers, Git servers, and accounts.

Overview

This guide helps you configure Git to use different SSH credentials per repository, rather than relying on a single global configuration. This approach allows you to:

• Access multiple Git servers (GitHub, GitLab, self-hosted instances)
• Use different accounts on the same server (personal and work accounts)
• Manage separate keys per computer for better security
• Easily revoke access if a device is lost or compromised

Want a visual overview first?

See the interactive SSH keys diagram before working through the steps below.

How it works

Git uses SSH to authenticate with remote servers. SSH identifies you using a key pair (public and private keys). By configuring SSH to use different keys for different “hosts,” you can route connections appropriately. The trick is using SSH host aliases that map to the actual server but specify which key to use.

Example scenario

Git servers:

• github.com
• gitlab.company.edu (work server)

Computers:

• Home laptop (Linux)
• Work Windows PC
• Work MacBook

Accounts:

• personal@example.com → GitHub personal account
• secondary@example.com → GitHub secondary account
• workid@company.edu → Company GitLab work account

Security strategy: Create separate SSH keys for each laptop. If a device is compromised or lost, revoke only that device’s key without affecting other machines.

Complete setup process

Step 1: Create SSH config file

The SSH config file tells SSH which key to use for which connection.

Linux/macOS

cd ~/.ssh
touch config
chmod 600 config

The chmod 600 command sets permissions so only you can read/write the file.

Windows

Navigate to C:\Users\YourUsername\.ssh\ and create a file named config (no extension) if it doesn’t exist.

Step 2: Generate SSH keys

Create one SSH key per account per computer. Use descriptive names that identify the device, account, and server.

Command:

ssh-keygen -t ed25519 -C "email@example.com" -f ~/.ssh/filename

Example naming convention for home laptop:

ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519_homelaptop_personal_github
ssh-keygen -t ed25519 -C "secondary@example.com" -f ~/.ssh/id_ed25519_homelaptop_secondary_github
ssh-keygen -t ed25519 -C "workid@company.edu" -f ~/.ssh/id_ed25519_homelaptop_work_gitlab

Note

You can set a passphrase for added security (recommended). This creates two files: filename (private key) and filename.pub (public key). Never share your private key.

Step 3: Configure SSH host aliases

Edit ~/.ssh/config to map custom host aliases to the actual servers with specific keys.

Example config:

Host personal.github.com
  Hostname github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_homelaptop_personal_github
  IdentitiesOnly yes

Host secondary.github.com
  Hostname github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_homelaptop_secondary_github
  IdentitiesOnly yes

Host work.gitlab.company.edu
  Hostname gitlab.company.edu
  User git
  IdentityFile ~/.ssh/id_ed25519_homelaptop_work_gitlab
  IdentitiesOnly yes

What each field means:

• Host — the alias you’ll use in Git commands
• Hostname — the actual server address
• User — always git for Git servers
• IdentityFile — path to your private key
• IdentitiesOnly yes — only use this specific key (don’t try others)

Step 4: Upload public keys to Git servers

GitHub

1. Copy your public key:

   cat ~/.ssh/id_ed25519_homelaptop_personal_github.pub

2. Log in to GitHub
3. Go to https://github.com/settings/keys
4. Click “New SSH key”
5. Paste the public key and give it a descriptive title (e.g., “Home Laptop”)

GitLab (company)

1. Copy your public key:

   cat ~/.ssh/id_ed25519_homelaptop_work_gitlab.pub

2. Log in to GitLab
3. Navigate to your SSH keys settings (typically under user settings)
4. Paste the public key and add a descriptive title

Step 5: Test SSH connection

Verify that authentication works using your host alias:

ssh -T personal.github.com

Successful response from GitHub:

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

Test each configured host:

ssh -T secondary.github.com
ssh -T work.gitlab.company.edu

Working with repositories

Cloning a new repository

Replace the standard hostname with your SSH config alias:

Standard clone command:

git clone git@github.com:username/website.git

Using SSH alias:

git clone git@secondary.github.com:username/website.git

The alias ensures the correct SSH key is used automatically.

Configuring Git identity per repository

After cloning, set the user identity for commits in that specific repository:

cd your-repo
git config user.email "you@example.com"
git config user.name "Your Name"

Caution

Use git config (not git config --global) to set these per-repository, not system-wide — otherwise every repo on the machine will use the same identity.

Updating existing repositories

If you have repositories that were cloned with the standard hostname, update them to use your SSH alias:

1. Check current remote URL:

git remote -v

Example output:

origin  git@github.com:username/repository.git (fetch)
origin  git@github.com:username/repository.git (push)

2. Update to use SSH alias:

git remote set-url origin git@personal.github.com:username/repository.git

3. Verify the change:

git remote -v

Updated output:

origin  git@personal.github.com:username/repository.git (fetch)
origin  git@personal.github.com:username/repository.git (push)

Quick reference

File locations

OS	SSH config location
Linux/macOS	~/.ssh/config
Windows	C:\Users\YourUsername\.ssh\config

Common commands

# Generate new key
ssh-keygen -t ed25519 -C "email@example.com" -f ~/.ssh/keyname

# View public key
cat ~/.ssh/keyname.pub

# Test SSH connection
ssh -T host.alias.com

# Clone with alias
git clone git@host.alias.com:username/repo.git

# Update remote URL
git remote set-url origin git@host.alias.com:username/repo.git

# Set repo-specific identity
git config user.email "email@example.com"
git config user.name "Your Name"

Troubleshooting

Permission denied (publickey)

Symptoms: Git operations fail with authentication errors.

Solutions:

1. Verify your public key is uploaded to the Git server
2. Test the SSH connection: ssh -T your.host.alias
3. Check SSH config syntax (no typos in paths or aliases)
4. Ensure private key file permissions are restrictive: chmod 600 ~/.ssh/keyname
5. Verify IdentityFile path in config points to the correct private key

SSH uses wrong key

Symptoms: Authentication succeeds but with the wrong account.

Solutions:

1. Add IdentitiesOnly yes to your SSH config host entry
2. Ensure you’re using the host alias in git commands, not the actual hostname
3. Check that the host alias in your Git remote URL matches your SSH config

“Could not open a connection to your authentication agent”

Symptoms: On some systems, SSH agent issues prevent key usage.

Solution: Start the SSH agent and add your key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/your_private_key

Best practices

1. Descriptive key names — include device, account, and server in the filename
2. One key per device — makes it easy to revoke access for lost/stolen devices
3. Use passphrases — protect your private keys with strong passphrases
4. Repository-specific config — never use git config --global for account-specific settings
5. Test after setup — always test SSH connections before attempting Git operations
6. Document your aliases — keep a note of which alias corresponds to which account

Resources

• Managing Multiple SSH Keys (Medium)
• Git Config Documentation (Atlassian)
• SSH Config File Guide (Linuxize)
• Testing GitHub SSH Connection (GitHub Docs)