Multiple Git SSH Key Pairs

This explains how to configure ssh to allow repos on multiple GitHub or BitBucket accounts to be developed on the same dev environment.

It assumes MacOS.

Basic Config

Usually, when using SSH (with git or otherwise), you'll have a single key pair for the machine you're on (eg. id_rsa). You might also define some default ssh options in your .ssh/config file. Something like this:

# Default options
Host *
   User ubuntu
   IdentityFile ~/.ssh/id_rsa
   AddKeysToAgent yes
   UseKeychain yes

With this setup, you can add your public key (eg. id_rsa.pub) to servers for SSH access as well as a single GitHub and/or BitBucket account for git. However, problem emerge if you need to use multiple GitHub and/or BitBucket accounts with different SSH keys. Both GitHub and BitBucket will block you from adding a key to multiple accounts.

Multiple Accounts

If you need to use multiple GitHub and/or BitBucket accounts with git over ssh, you'll need an additional key pair for each account. Using your default SSH key pair for git access will cause problems. That is, if you need to configure two BitBucket accounts you need three key pairs: your default one plus one for each BitBucket account.

Creating Keys

Ok, let's create a new SSH key.

We need to pick a filename and key comment. Neither the comment or the filename have any technical meaning; they're just labels. I like mine to be quite descriptive and include my name, the machines name and model, the purpose of the key and the year in which it was created. Lets put our values into variables to make the other commands a bit clearer:

# Config for our new Thinkmill BitBucket key
SSH_KEY_COMMENT="John Molomby (Thinkmill) @slab; Mac mini (early 2020); Thinkmill BitBucket"
SSH_KEY_PATH="$HOME/.ssh/id_ecdsa-slab-molomby-2021-thinkmill-bitbucket"

Next, we create the key pair. Here we've used the ECDSA algorithm which I prefer to RSA (but it doesn't matter much).

# Create the key pair
ssh-keygen -t ecdsa -b 256 -C "${SSH_KEY_COMMENT}" -f "${SSH_KEY_PATH}"

You'll be prompted for a pass phrase; set on if you like. Our ssh config will store the pass phrase in your MacOS keychain anyway so you'll only have to enter it once.

Next copy the public key to the pasteboard so we can manually add it to the relevant BitBucket/GitHub account.

# Copy the key to the pasteboard
cat ${SSH_KEY_PATH}.pub | pbcopy

You'll need to repeat this process for each account (BitBucket, GitHub, etc.) you want to auth against.

SSH Config

Each account your setting up needs a config block in your .ssh/config. Each config block should specify a Host alias we can use to reference the account; the HostName specifies the true hostname. The relevant private key should be configured as the IdentityFile and the User should be git.

For example, if we were setting up two BitBucket accounts, one for Thinkmill and one for Brighte, we'd need something like this:

# Thinkmill BitBucket
Host thinkmill.bitbucket.org
   HostName bitbucket.org
   User git
   IdentityFile ~/.ssh/id_ecdsa-slab-molomby-2021-thinkmill-bitbucket

# Brighte BitBucket
Host brighte.bitbucket.org
   HostName bitbucket.org
   User git
   IdentityFile ~/.ssh/id_ecdsa-slab-molomby-2021-brighte-bitbucket

# Defaults
Host *
   User ubuntu
   IdentitiesOnly yes
   IdentityFile ~/.ssh/id_rsa
   # MacOS settings
   AddKeysToAgent yes
   UseKeychain yes

You can still include your defaults but remember to put them at the end. The the ssh client uses the first value it finds matching the current hostname so, if you put the Host * block at the top it will override your other settings rather than act as defaults.

Here we've also added the IdentitiesOnly yes directive to our defaults. This can prevent problems with additional keys being sent to the ssh (or git) server.

Cloning

To clone a repo from either account, you'll need to modify the repo URL to substitute the original hostname for the alias you've added to your .ssh/config.

For example, if the clone URL given by BitBucket is [email protected]:brighte-energy/energy-api.git you'd need to replace bitbucket.org with brighte.bitbucket.org. This causes your git client to match against the relevant ssh config block.

Your clone command would then be:

git clone [email protected]:molomby-brighte/testing.git

Once cloned, the repo will operate as usual.

Troubleshooting

You can troubleshoot ssh connection/authentication issues using your ssh client by attempting to connect to the git server using the alias you've configured. Eg.

ssh brighte.bitbucket.org -v

This will output information about the authentication process and which keys are used. It will end with an error (because shell access will likely be disabled on the git server) but, just before that, you should see the user you're being successfully authenticated as:

logged in as molomby-brighte

You can use git to connect to Bitbucket. Shell access is disabled
debug1: channel 0: free: client-session, nchannels 1
Connection to bitbucket.org closed.
Transferred: sent 2804, received 1704 bytes, in 0.5 seconds
Bytes per second: sent 5434.8, received 3302.7
debug1: Exit status 0

molomby/210607 Git keys.md