Up until now, I have not needed to manage multiple SSH keys on a single machine. I have always used one SSH key for my personal GitHub account, which my job has allowed me to use when working on the company repo. Recently, we had to move the repo over to GitLab. Also, we started another project on GitHub which now can only be accessed by my company account. So now I have my personal GitHub account, work GitHub account, and work GitLab account.
I decided to look into how SSH keys work, how we can connect them to GitHub and GitLab, and how we can manage multiple without having repo permissions clash with each other. It wasn't easy to get all my answers, and I needed to look into a lot of different sources. So I decided to share what I learned about how all of this works.
Note: The environment I am working in is Windows with WSL. Everything I have listed here should work with Linux, and Windows if you either have Git Bash or WSL. As for Mac, some of the sources I link should point you in the right direction.
First thing we need to know is how we can create SSH keys that we can use to link to our GitHub/GitLab. There is a very easy way to do this in our terminals.
- Generate a key
ssh-keygen -t ed25519 -C "your_email@example.com"Make sure you change the email inside the quotes to an email of yours.
This will generate a key using the ed25519 encryption algorithm, and uses the provided email as a label so you can easily identify it. You can change the algorithm you would like to use to encrypt your key, but GitHub recommends using this one.
- Enter the file in which you would like to store your key
> Enter a file in which to save the key (/home/YOU/.ssh/id_ALGORITHM):[Press enter]Pressing enter will save the file in the default location:
~/.ssh/id_ed25519.I recommend naming the file something easily identifiable like
id_ed25519_work_github, especially if you plan on having multiple SSH keys on one machine. It is common for people to prepend their file names with id and the algorithm they are using.
- Enter a passphrase (Optional)
> Enter passphrase (empty for no passphrase): [Type a passphrase] > Enter same passphrase again: [Type passphrase again]Using a passphrase is an extra layer of protection for your SSH keys. If someone ever gets access to your private key, they have access to your stuff. The passphrase prevents this from happening!
If you decide to use a passphrase, you will always be asked what that passphrase is every time you do a pull or push to your remote repository. There is a way to avoid this by using keychains. If you would like to know more about this, here is a link to get more info: Ubuntu / Debian Linux Install Keychain SSH Key Manager For OpenSSH
Note: I have seen this also solved by using ssh-agent to add all of your keys. They put this in their .bashrc to automate it when you first boot up your machine, but I have never done it myself so I can't speak on it.
This is the most important part when it comes to managing multiple keys. Your ssh config will tell your SSH client where it should be looking for your SSH keys, and which key it should be using.
If you have multiple SSH keys, or if you have a single key and changed the name or location of that key, you will need a SSH config to fix some issues you will have.
- Create an SSH config file
Move to your .ssh directory and create a config file.
cd ~/.ssh && touch config
- Open config and copy the example:
Host github.com Hostname github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yes Host work.github.com Hostname github.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yes Host work.gitlab.com Hostname gitlab.com User git IdentityFile ~/.ssh/id_ed25519_work_gitlab IdentitiesOnly yesMake sure you change up the file to work for you. Host can be anything you want (it should easily identify what host you are using and what work you are doing). Hostname should always be the website you are connecting to. Identity file should point to the SSH private key file name you are going to use.
In the Clone Your Repo Section, it should make sense how we can connect different repos to different keys. It is very important to realize that this SSH config file is telling your SSH client which key it should be looking for every time its setting up a connection from a certain host.
You will need to add your public key to the host you are trying to connect to (GitHub/GitLab). This allows the host to connect with your machine through SSH in a very secure way. Connecting your SSH key is very simple.
- Copy the SSH key to your clipboard.
You will need to copy your public key (NOT YOUR PRIVATE KEY!). Copy the example code, and make sure to point to the correct public key.
Linux
xclip -sel clip < ~/.ssh/id_ed25519.pubGit Bash on Windows
cat ~/.ssh/id_ed25519.pub | clip
-
In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.
-
In the "Access" section of the sidebar, click SSH and GPG keys.
-
Click New SSH key or Add SSH key.
-
In the Title field, add a descriptive label for the new key. For example, if you're using a home desktop, you could call this key "Home Desktop".
-
Select the type of key, either authentication or signing. I always just choose authentication which is the default.
-
In the Key field, paste your public key.
-
Click Add SSH key.
-
If prompted, confirm access to your account on GitHub.
- Copy the SSH key to your clipboard
You will need to copy your public key (NOT YOUR PRIVATE KEY!). Copy the example code, and make sure to point to the correct public key.
Linux
xclip -sel clip < ~/.ssh/id_ed25519.pubGit Bash on Windows
cat ~/.ssh/id_ed25519.pub | clip
-
Sign in to GitLab.
-
On the left sidebar, select your avatar.
-
Select Edit profile.
-
On the left sidebar, select SSH Keys.
-
Select Add new key.
-
In the Key field, paste your public key.
-
In the Title field, add a descriptive label for the new key. For example, if you're using a home desktop, you could call this key "Home Desktop".
-
Optional. Select the Usage type of the key. It can be used either for Authentication or Signing or both. Authentication & Signing is the default value.
-
Optional. Update Expiration date to modify the default expiration date.
-
Select Add key.
You should test your SSH connection before trying to clone your repository. Here are some links that tell you how you can test your SSH connection:
This is where our config will start to make sense. When you usually clone your repo to your machine locally, you can just copy the SSH URL. Well now we have to change up the URL just a bit.
Below are examples of each part of the config, and how you would clone a repo for each SSH key:
- Personal SSH key (GitHub)
Config:
Host github.com Hostname github.com User git IdentityFile ~/.ssh/id_ed25519_personal IdentitiesOnly yesGit clone:
git clone git@github.com:profile/repo.git
- Work SSH key (GitHub)
Config:
Host work.github.com Hostname github.com User git IdentityFile ~/.ssh/id_ed25519_work IdentitiesOnly yesGit clone:
git clone git@work.github.com:work-profile/repo.git
- Work SSH key (GitLab)
Config:
Host work.gitlab.com Hostname gitlab.com User git IdentityFile ~/.ssh/id_ed25519_work_gitlab IdentitiesOnly yesGit clone:
git clone git@work.gitlab.com:work-profile/repo.git
It is actually surprisingly easy to get this all set up. You create your SSH key, set up an SSH config, connect your public key to the host, and clone your repo. If there are any concepts I didn't really touch up on, there are tons of great resources that go much more in depth than I did. The intention of this was to get you a quick way to get your SSH keys set up in a simple way.