Add additional SSH troubleshooting while managing multiple GitHub accounts on a Single workstation

[greninja517]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts

What part(s) of the article would you like to see updated?

What is the problem?

Currently, GitHub Docs do not provide a detailed guide on configuring SSH for multiple GitHub accounts on a single workstation. Many developers face issues such as:

• SSH key conflicts when trying to use the same SSH key for multiple accounts (error: "key already in use").
• Inability to assign multiple SSH keys to the same host (github.com).
• Needing to update Git remote URLs when using aliases in ~/.ssh/config.

---

What is the proposed solution?

I’d like to contribute a troubleshooting section that:

• Explains why SSH conflicts happen when managing multiple GitHub accounts.
• Shows how to configure unique host aliases in ~/.ssh/config.
• Provides a step-by-step guide for updating Git remote URLs accordingly.

---

💡 Step-by-Step Guide to Fix This Issue

When managing multiple GitHub accounts on a single workstation using SSH, users may encounter authentication conflicts. Here’s how to set up SSH properly:

1️⃣ Generate Separate SSH Keys for Each Account

You cannot use the same SSH key for multiple GitHub accounts. Generate two different SSH keys:

ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/id_rsa_github_personal
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/id_rsa_github_work

Add the generated public keys id_rsa_github_personal.pub and id_rsa_github_work.pub on the respective accounts.

2️⃣ Configure ~/.ssh/config with Unique Host Aliases
Since GitHub only recognizes github.com as the host, you must define aliases to specify different SSH keys:

# Personal GitHub Account
Host github-personal
    HostName github.com
    IdentityFile ~/.ssh/id_rsa_github_personal
    User git
    IdentitiesOnly yes

# Work GitHub Account
Host github-work
    HostName github.com
    IdentityFile ~/.ssh/id_rsa_github_work
    User git
    IdentitiesOnly yes

3️⃣ Handling Networks that Block SSH on Port 22
Some networks block SSH connections on port 22. To use GitHub’s SSH over port 443 instead, modify your config:

# Personal GitHub Account
Host github-personal
    HostName ssh.github.com
    IdentityFile ~/.ssh/id_rsa_github_personal
    User git
    Port 443
    IdentitiesOnly yes

# Work GitHub Account
Host github-work
    HostName ssh.github.com
    IdentityFile ~/.ssh/id_rsa_github_work
    User git
    Port 443
    IdentitiesOnly yes

4️⃣ Update the Git Remote URL
To ensure Git uses the correct SSH key, update the remote repository URL:

Check the Current Remote URL

git remote -v

Output:

origin  [email protected]:username/repository-name.git (fetch)
origin  [email protected]:username/repository-name.git (push)

Update the Remote URL
Change github.com to:

• github-personal for personal repositories
• github-work for work repositories

# For Personal Repos
git remote set-url origin git@github-personal:username/repository-name.git

# For Work Repos
git remote set-url origin git@github-work:orgname/repository-name.git

5️⃣ Test the SSH Connection
Run the following commands to verify that SSH authentication works correctly:

ssh -T github-personal

ssh -T github-work

Output:

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

---

Why is this useful?

This guide will help developers who frequently switch between personal and work GitHub accounts. By following these troubleshooting steps, users can correctly configure SSH without running into authentication conflicts.

I’d love to contribute this section to the official GitHub Docs. Let me know if this would be valuable, and I can submit a pull request with the content. 🚀

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[isaacmbrown]

Hi @greninja517! Thanks for the proposal and all the details, appreciate you taking the time to outline your ideas! ✨ I've triaged this for a writer to review

[isaacmbrown]

Hi again @greninja517 - could you expand a bit more about what problems you're aiming to address that this existing section doesn't account for? Thanks!

[greninja517]

Hello, @isaacmbrown
I initially thought that there was no existing documentation addressing this issue. However, I found that the 'Contributing to multiple accounts using SSH and GIT_SSH_COMMAND' section already provides a solution using GIT_SSH_COMMAND. Since git config core.sshCommand offers a persistent and more convenient approach for managing multiple accounts, I now see that .ssh/config is not necessarily required in most cases. Given this, I believe my contribution may not add significant value beyond what’s already documented.

However, we can add the alternative option of setting up the ~/.ssh/config file in the documentation if maintainers don't find it unnecessary. Both ways provide the solution for managing the multiple accounts differently.

I would like to suggest small suggestion in that existing section. To enhance that section, we can add:

git config core.sshCommand "ssh -i ~/.ssh/private_key -o IdentitiesOnly=yes"

just below the GIT_SSH_COMMAND.
I will go ahead and close the issue if you find it neccessary for setting up the ~/.ssh/config file. Thanks !

[isaacmbrown]

Thanks for getting back to us @greninja517! Generally we like to avoid introducing too many decision points, and aim to provide a single way of accomplishing a task where possible. I'll close this issue but we appreciate the thought and detail you provided ✨ Thanks!