I’ve done the “creating and adding SSH keys from Git to Github” process possibly 5 times now in the past 3 -4 years. Each time I had to just follow along blindly with the Github guide and cross my fingers and pray I got all of the black magic incantations correct and didn’t accidentally unleash the hordes of hell upon the world by my copy/pasting.
So recently I got a new laptop and the day I bought it I remember being happy I had a nice new laptop with a touch screen and Windows 8, which I really like! I’m not an idiot who can’t adjust to a new menu. “Oh Noes! A menu that covers the entire screen instead of just a quarter. How will ever manage??”. Come on people!
Anyways, as I was saying I was happy about my new laptop but there was an underpinning of doom! I know at some point I was going to have to set up all my dev software from servers, to IDEs and of course…SSH access to Github. Dun Dun DUUUUUNNN. So this time I decide enough was enough. The Github guide is enough to get the job done but I want to understand what the heck I’m doing and why. I started into the process but instead of just copying and pasting and finger-crossing I researched each command. I Googled and Bingled and Stackoverflowgled my way to figure out what each part was doing and why. I went from copying and pasting to straight up typing it all out from memory in about an hour. And I fully understood it so I full control. The black magic was in my control now!
So I thought I’d write an in depth tutorial of getting setting up SSH Keys for use with Github so you too can stop dreading the black magic of SSH and take control of its power. Here goes…
Check for pre-existing SSH keys
The first thing you should do if you are on a machine which perhaps already has Git installed or your or other people have used for server-side development is check if you already have an SSH key on your machine. It could be for any reason but you could already have an SSH key. SSH keys are not just for connecting your machine to Github. You also use SSH to connect to Amazon AWS, Microsoft Azure and many other Cloud Based systems.
The SSH key you are about to create would be your personal or “private” SSH key. Any service you wish to SSH into using the private => public key authentication, not just Github would require your private key and public key which is placed on that service (for example Github). The service then compares your private key with it’s key (public key) and together they form your authenticated secure connection with that service. For that reason, you may already have created an SSH key and, if so, you can (and probably should) simply use that key.
To Check for an Existing SSH key
To check for an existing ssh key open Git Bash and run
ls -a ./.ssh
You will either see a list of files one of which should be in the following list:
Otherwise you will see an empty folder or an error:
ls: Cannot access /.ssh: No such file or directory
This means there is no such folder. So no SSH keys have ever been generated.
WINDOWS: If you’re on Windows and using the latest (Jan 2016) Git Bash you might have a false positive because Git actually doesn’t look in the right directory when doing
ls -a ./.ssh. You should double check with:
When we generate our key it will create this folder and the required file. Most likely id_rsa.pub or id_rsa
Creating a new SSH Key
To generate a new SSH key we use the ssh-keygen unix command. We will be using it with the following flags:
-t rsa => This is the type of key we want to generate. You can choose from dsa, ecdsa, ed25519, rsa or rsa1. For Github we will be using rsa.
-b 4096 => This is the number of bits (or characters) you want in the key. For RSA keys, the default is 2048 bits. Github requires 4096 bit RSA keys for authentication.
-C "[email protected]" => This is a comment or a labal for this RSA key. Github recommends it the email associated with your Github account.
-C flag for comment is uppercase. A lowercase “c” is for something completely different and only works with rsa1.
The above flags are all you require to create a suitable SSH key for use with Github. The full command is:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
What if I already have a key and I want to keep it?
You might already have an SSH key and you don’t want to delete it. Maybe it’s in use on another service. Or perhaps it’s dsa or it’s rsa but doesn’t have a comment or it’s only 2048 bits.
In these cases you will need multiple SSH keys. To this you can add the following flag to the above command:
-f output_keyfile => This is the file you want to save your key to. You do not need to specify an extension. Also, by convention you should use all lowercase with underscores, not hypens. Definitely no spaces!
Your code to create a new SSH file would look like:
ssh-keygen -t rsa -b 4096 -C "[email protected]" -f ~/.ssh/your_file_here
After all of that you should see something like the following:
Your identification has been saved in /c/Users/YourUserName/.ssh/your_file_here.
Your public key has been saved in /c/Users/YourUserName/.ssh/your_file_here.pub.
The key fingerprint is:
SHA256: SoMeRanD0MJuNkAnDCraPHeReThaTIsVeRyLongBla [email protected]
The key's randomart image is:
| some random |
| symbols |
| and junk |
Or you could just use the normal command with no -f flag and enter another filename…but what’s the fun in that?
Turn on the SSH Agent
Right now all you have done is create the public and private keys. However, just as you would need to add the public key to Github so you know your connecting with Github when you make an SSH connection, you also still need to add the private key to your own SSH Agent so Github can identify you.
To do this you first turn on your SSH Agent with the following command:
eval $(ssh-agent -s)
If that doesn’t work you may need to wrap the
$(ssh-agent -s) in double quotes:
eval "$(ssh-agent -s)"
The next step is to add your private key from
id_rsa to the SSH Agent using ssh-add:
Now if you run:
you will see the id_rsa key, and possibly others if you have more than one ssh added to the SSH Agent.
Adding your SSH Key to Github
Finally, we’re ready to add the public key to Github so we can connect securely and easily. The reason we do all of this is so we can securely gain access to our repositories every time we want to clone, push, pull or fetch through Git.
First copy the contents of the file in .ssh/id_rsa.pub to your clipboard. You can either open it in a text editor and copy it that way or you can use the command:
clip < ~/.ssh/id_rsa.pub
Then log into you Github Account and:
- hover on your profile icon on the top right and go to Settings
- On the left Sidebar Menu go to SSH keys
- Click the Add SSH key button in the upper right corner of the SSH keys panel
- Paste the key into the Key textarea and give it a Title you’ll recognise that you’ll associate with this key. I generally use the Computer name.
- Click Add Key to save.
That’s it! You now not only know how to give yourself SSH access to Github but also what is actually going on. This will help you correct mistakes or just play around and get comfortable with doing this. Also, everythin you’ve learned here will help you if you need to add private/public SSH key pairs to other services for anything.
Leave a comment if you have any problems or questions.