Here’s an interesting challenge. You have a personal laptop that you want to use to access both your personal GitHub account as well as your work GitHub account. Or maybe you have a number of clients and you need GitHub access to all of them from a single system. Sounds easy enough until you realize that you can not reuse ssh keys on GitHub so i.e., you can’t just have a single key and install it in multiple GitHub accounts. No worries though, this is not all that hard to set up! These instructions are specific to MacOS, will probably be very similar on Linux and well, if you are using some kind on Linux simulation on Windows they may work as well.

Set Up SSH

You may have already done this step but, for completeness, generating a key will look something like:

% ssh-keygen -t ed25519 -C "your_email@example.com"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/wyllie/.ssh/id_ed25519): ~/.ssh/key1_ed25519
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in key1_ed25519
Your public key has been saved in key1_ed25519.pub
...etc

The key name can really be anything. It’s a convention to include the key type in the name, in this case it’s ed25519 but it’s not required. All of these keys will be in your ~/.ssh directory though, so it’s not a bad idea to name them in a way that makes it easy to quickly sort though them. I typically use a name like github_ed25519_company1 but it’s really just personal preference though.

Use the same process to create as many keys as you need, one for each GitHub account you will need to connect to.

Once you have all of your keys created, cd over to your ~/.ssh directory. You may already have a config file or you can create a new one with:

% touch config && chmod 600 config

If the file does already exist, you may want to check that the permissions are set to 600 (user read/write) to avoid a lot of trouble shooting later on.

Now open up the config file and set it up to look something like this:

Host github.com-company1
  HostName github.com
  AddKeysToAgent yes
  UseKeychain yes
  User git
  IdentityFile ~/.ssh/github_ed25519_company1

Host github.com-company2
  HostName github.com
  AddKeysToAgent yes
  UseKeychain yes
  User git
  IdentityFile ~/.ssh/github_ed25519_company2

Once the configuration is set up, start up ssh-agent and then add the ssh keys to the agent:

# start up ssh-agent
% ssh-agent -s
  
# now add the keys to the agent
% ssh-add --apple-use-keychain ~/.ssh/github_ed_25519_company1
# ...etc, for each key

Configure GitHub

Once you have the keys set up, you can add them to the various GitHub accounts you are connecting to. Use the instructions from GitHub to figure this out if you have never done it before -> GitHub SSH Keys.

Configure Git

A lot of the way the rest of this sets up is going to be personal preference. I like having my configurations separate from the code. I also keep my GitHub repos one level deep in my home directory since I only have a couple of these. If you have a lot of clients and a lot of keys, you may want to arrange this in a different way. It’s all just messing with the paths though, there is no right way or standard way to set this up.

That said, lets say we have two keys github_ed25519_company1 and github_ed25519_company2 as well two directories in your home directory called ~/Company1 and ~/Company2 which will store all of the repos for each client.

The way I’m going to proceed is to create a directory for all of my GitHub configuration files called ~/.gitconfig.d, inside this directory I’m going to create a git configuration for each company. The directory tree is going to look something like:

~/.gitconfig.d
        company1.gitconfig
        company2.gitconfig

Side note here:

Another way to handle this is to put the configuration files in the same directory as the source code repos in which case you could call your config files would be in ~/Company1/.gitconfig . My only problem with this approach is that, to me at least, it seems like these files might be harder to track. The way I have set it up, you could track all of the config files in source control if you really wanted to. For example, this might come in handy if you have multiple computers.

Once you have decided how you want to organize everything, you can can create the files. They need to look like this:

# This is Git's per-user configuration file.
[user]
        name = Andrew Wyllie
        email = wyllie@comapny1.com

[url "git@github.com-company1"]
        insteadOf = git@github.com

The [user] part identifies the account I’m using on GitHub. The [url] part is going to tell the git command to use the SSH key called git@github.com-company1 as opposed to (insteadOf) git@github.com. So basically, this configuration file is just telling the git command which SSH key (as defined in the ~/.ssh/config file) to use for Company1.

Once the company specific configuration files are in place we can configure the main ~/.gitconfig file in the home directory. In this file we are going to set up a bunch of links to the company files. The ~/.gitconfig file will look like this and watch that you add that trailing slash (/) after Company1/:

[includeif "gitdir:~/Company1/"]
        path = ~/.gitconfig.d/comapny1.gitconfig

[includeif "gitdir:~/Company2/"]
        path = ~/.gitconfig.d/company2.gitconfig

The way to read this is - If I’m currently in the directory ~/Company1/ then use the configuration file for Company1 which is found at the location ~/.gitconfig.d/company1.gitconfig . Same idea for Company2 . Again, you don’t have to use this directory layout, you can put the configuration files wherever you like and you do not have to follow the naming conventions I’m using. At this point, everything should be working flawlessly, right? If you change directory into ~/Company1 you should be able to clone repos that are attached to your Company1 GitHub account.

It’s not working :-(

There are a few things that can go wrong with this set up and unfortunately it’s not all that easy to test/troubleshoot as a lot of this stuff just fails silently. Here are some things you can try:

Make sure your SSH key can connect to GitHub. A simple way to do this is to comment out all of the keys in your ~/.ssh/config file, except for one and then change the name on the Host line so the it just reads Host github.com. This should get you into that company’s GitHub account - if not, make sue that you have installed the key correctly on GitHub, make sue that the permissions are correct on the ~/.ssh/config file and that you have the paths to the keys correct
Check that your .gitconfig file is configured correctly. You can run this command to make sure that git is seeing the configuration files that you have configured for the each company. To check it out:

% git config --global --list --show-origin
file:/Users/wyllie/.gitconfig   includeif.gitdir:~/Company1/.path=~/.gitconfig.d/company1.gitconfig
file:/Users/wyllie/.gitconfig   includeif.gitdir:~/Company2/.path=~/.gitconfig.d/company2.gitconfig

If you make changes to the ~/.gitconfig file, you will need to run the following command:

git config --global --unset-all file./Users/wyllie/.gitconfig

and then rerun the first command.

Hopefully these help troubleshoot a bit. As I mentioned earlier, this is a bit of a pain to troubleshoot but if you keep at it you can figure it out. If you need help or if I missed anything, feel free to add a comment below!