How to Configure Multiple GitHub Accounts with SSH

Set up your first GitHub account? Check! Followed GitHub’s guide to successfully connect to Github with SSH? Check!

But … now you need more than one GitHub account for work or school and your stuck wondering how to push or pull from different accounts? Then follow along to learn how to setup multiple Github accounts to connect from your local machine.

In this tutorial, you’ll learn:

How to check for existing and generate new SSH keys for multiple Github accounts
How to configure your SSH config file to handle multiple GitHub accounts
How to add a remote repository to handle multiple Github accounts

By the time you’ve finished with this tutorial, you’ll be effortlessly pushing to multiple Github accounts from your local machine like a pro.

This tutorial assumes no prior knowledge of Git, so a real-world example scenario has been provided to give you more context to ensure clarity. You can tailor each step to your specific situation, using the example scenario as a guide to fully understand the process.

Let’s dive right in!

Example Scenario

Meet John doe, a software developer who is managing multiple GitHub accounts between various projects for work and personal.

JohnDoeAcme: This Github account is specifically assigned for all coding projects John is working on at ACME Corporation, a fast-paced tech startup he works at full-time.
JDoeFreelance: John also likes to freelance on the side. This Github account lets him manage and organize all his freelance projects separately without getting mixed up with his ACME activities.
DoePersonal: Last but by no means least, John holds this Github account for all his personal projects, learning endeavors, and open-source contributions out of office hours.

Using the example scenario above, you’ll learn how to configure a local Git environment on a Mac to handle three different Github accounts. This will allow you to seamlessly push and pull between different accounts.

Step 1: Check for existing SSH keys

First, you should check if you’ve already created SSH keys for the Github accounts you want to use. If you haven’t already then you’ll need to create them since Github uses SSH keys to establish a secure connection between your computer and the Github servers.

Check for existing keys:

ls -al ~/.ssh

If you see files ending in .pub then you have existing keys, for example:

id_rsa.pub
id_ecdsa.pub
id_ed25519.pub

If you see all the existing key’s for your GitHub accounts that you want to use then skip to Step 3.

Otherwise, if one or more accounts that you want to use is missing then proceed to step 2 to create new SSH key’s for those accounts.

For example, in John’s case, he had already setup his personal Github account using SSH following the official GitHub documentation on Generating a new SSH key and adding it to the ssh-agent . As a result, after running the command to Check for existing keys he see’s his key for his personal Github account:

id_ed25519.pub

Tip: Notice how the name of the key does not provide specific information to indicate that this is John’s personal account. Just by looking at the file name, it is isn’t clear what this key is for. It might be manageable for now since John Doe only has one account but once he starts adding multiple accounts things will start to unravel. When you reach the step to create your keys there will be helpful tips for naming your keys to ensure they are consistent, specific and identifiable. But don’t worry for now, just be mindful of this.

John is not provided with a work laptop since he works at a startup. So John needs to add his work Github account to his personal laptop. In addition, he likes to freelance on the side so he plans to add his freelance Github account as well.

As a result, John proceeds to step 2 to create new SSH key’s for his personal and freelance Github accounts.

Step 2: Generate new SSH key’s for each Github account

Create a new SSH key using the ed25519 algorithm, remember to replace your_email@example.com with your email:

ssh-keygen -t ed25519 -C "your_email@example.com"

When you’re prompted to “Enter a file in which to save the key”:

> Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Press enter]

Type out the full path where you want to save your SSH Key and replace id_ALGORITHM with any name of your choice. Just make sure to be consistent, descriptive, and identifiable.

Tip: Unsure what to name it? Try this convention id_ALGORITHM_ORG_SERVICE_USERNAME:

ALGORITHM represents the encryption algorithm used, such as rsa or ed25519.
ORG represents your organization, eg. acme.
SERVICE represents the associated service, eg. github.
USERNAME represents the GitHub username associated with the key, eg. johndoeacme to represent John’s work Github account.

For example, John Doe’s Github username for work is JohnDoeAcme so at the prompt he enters:

/Users/<username>/.ssh/id_ed25519_acme_github_johndoeacme

Replace <username> with your username. Unsure what your username is? Run this command to find out:

whoami

When prompted, type a secure passphrase.

Tip: You can just press enter to bypass adding a pass phrase but be warned that without a passphrase if your keys are leaked then anyone with your key can access your account. The passphrase, serves as an additional layer of security. For more information, see ”Working with SSH key passphrases”

Repeat Step 2 for each of your Github accounts. In John Doe’s case he will repeat Step 2 again for his freelance Github account before proceeding to step 3.

Step 3: Map your SSH keys to your Github Accounts

Once unique SSH keys have been created for each of your Github accounts, we need to tell git which SSH key belongs to which account.

That’s where the SSH config file comes in. It’s the key to switching between multiple Github accounts. Git uses this file to map out which SSH key belongs to which account. This is how git knows which identity to use for which host to connect so that it can seamlessly switch between multiple Github accounts on a single computer.

Check for an existing config file:

open ~/.ssh/config

Create one if it does not exist:

touch ~/.ssh/config

Open your config file and add the following placeholder template:

Host SERVICE.com-USERNAME
  HostName SERVICE.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ALGORITHM_ORG_SERVICE_USERNAME

SERVICE represents the associated service, eg. github.
USERNAME represents the specific user associated with the key, eg. johndoeacme .
id_ALGORITHM_ORG_SERVICE_USERNAME is the same placeholder used in step 2

Note: UseKeychain tells MacOS to remember the passphrase to your key and automatically supply it when needed so that you don’t have to type it out each time. Remove UseKeychain line if your not running MacOS or if you don’t want to add a passphrase to your key.

Repeat, until all your other accounts are added to the Config file.

In John Doe’s example, here is how his config file looks like after he finishes adding all his Github accounts using the placeholder template:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
  
Host github.com-johndoeacme
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519_acme_github_johndoeacme

Host github.com-jdoefreelance
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519_freelance_github_jdoefreelance

Step 4: Add your private SSH Key’s to the ssh-agent for Seamless Connection to GitHub

This step is optional, but highly recommended. If you skip this step, then you will need to supply the passphrase for your SSH key each time you try to push or pull from the server.

4.1: Start the SSH agent

Start the ssh-agent in the background and sets the environment variables that are needed for ssh-agent to communicate with ssh-add and ssh:

eval "$(ssh-agent -s)"

Step 4.2: Add your SSH private key’s to the ssh-agent

If you haven’t already started the ssh-agent then refer to step 4.1 before proceeding.

Add your SSH private key to the ssh-agent so that you don’t have to type a password every time you connect to the GitHub server.

ssh-add --apple-use-keychain ~/.ssh/id_ALGORITHM_ORG_SERVICE_USERNAME

Tips:

Remember to replace the placeholder id_ALGORITHM_ORG_SERVICE_USERNAME with the SSH private key associated with the Github account you want to add.
The option --apple-use-keychain is for MacOS only. It adds the passphrase to your keychain helping you manage the passphrase. If you did not add a passphrase to your key then run the command without the --apple-use-keychain option.

Repeat Step 4.2 until you have finished adding all your SSH private key’s to the ssh-agent for all your Github account.

Step 5: Add public key’s to your Github account’s

The public key is the key that you share with others or add to your GitHub account. The private key is the one that you should never share.

Think of it like this: the public key is like a lock, and the private key is like the unique key to that lock. You can give out the lock (public key) to people (in this case, Github) so they can lock things meant for you, while the key to that lock (private key) remains only with you. Anyone can lock the lock, but only you can unlock it.

By doing this, you’re providing GitHub with a way of verifying that it’s really you trying to interact with your repositories and not someone else.

To add your public key to your GitHub account, you would need to visit the GitHub website, go to your settings, and then move to SSH and GPG keys. From there you can add your new public key. For more information see Adding a new SSH key to your GitHub account.

Step 6: Verify Your Connection to Multiple GitHub Accounts Using New SSH Keys

On your local machine, let’s begin by setting up a new project to ensure you can connect to GitHub when pushing and pulling changes.

Create a new directory for your test repository by replacing <USERNAME> with your specific GitHub username. For example, if John wants to test with his work GitHub account johndoeacme, he would use:
```
mkdir ~/GitHub/test_repository_johndoeacme
```
Navigate into your new project directory:
```
cd ~/GitHub/test_repository_<USERNAME>
```
Create an empty README file:
```
touch README.md
```
Initialize your project with Git:
```
git init
```
Check the current username and email configuration for your repository:
```
git config user.name
git config user.email
```
If these are empty or not what you expected, set your username and email with the following commands:
```
git config user.name "Your Name"
git config user.email "Your Email"
```
For example, John would enter:
```
git config user.name "John Doe"
git config user.email "john.doe@acmecorp.com"
```

Step 6.1: Create a New Repository on GitHub

Log into GitHub.com with the account to which you want to push this test project.
Create a new repository by following these detailed steps on creating a new repository. Make sure you remember or note down the repository name as you will need it in the following steps.

Step 6.2: Test Your Ability to Push to the Remote Repository

Now that your remote repository is ready, let’s connect your local project to it.

Navigate to the root directory of your project if you haven’t already:
```
cd ~/GitHub/test_repository_<USERNAME>
```
Link your local repository with the remote repository by using the custom SSH URL format, adjusting <USERNAME> and <REPOSITORY_NAME> as appropriate:
```
git remote add origin git@github.com-<USERNAME>:<USERNAME>/<REPOSITORY_NAME>.git
```
- <USERNAME> should be your GitHub username.
- <REPOSITORY_NAME> is the name of the repository you created in step 6.1.
Tip: To make sure your SSH configuration is set up correctly, check your SSH config file.
```
open ~/.ssh/config
```
Verify that the remote repository was successfully added:
```
git remote -v
```
The output should list the URL for your repository associated with the alias ‘origin’, confirming the link.
Push the initial contents of your local project to the GitHub repository:
```
git push -u origin main
```
This command pushes your changes to the ‘main’ branch on GitHub and sets it to track the remote ‘main’ branch for future pushes.

Final Step: Verify the Configuration by Pushing to GitHub

Navigate to your repository on GitHub.com to ensure the new changes you pushed are visible on the website.
Congratulations! You have successfully configured a new GitHub account and securely connected it with SSH. This successful push confirms that your SSH settings and Git configuration are correctly set up for your account.

To verify that your setup works correctly across different accounts, repeat step 6 for any other GitHub accounts you manage. For example, John should carry out step 6 once more for his freelance account, JDoeFreelance, to confirm everything is configured correctly.