Configure SSH for GitHub Access

In order to access GitHub repos, you'll need to setup your SSH correctly.

In your shell (use Git Bash if you are on Windows), type in the following:

ssh -T git@github.com # -T means testing

The response will inform you whether your SSH access to GitHub is already setup. If it gives back something like:

Hi <user>! You've successfully authenticated, but GitHub does not provide shell access.

Then you are good to go, otherwise, we'll need to do the following:

  1. create an SSH key for your GitHub account.
  2. upload the SSH key to your GitHub account, so GitHub knows to match that key to you.
  3. configure your SSH client to use the key.

If this is the first time you are connecting to GitHub, you will also see a variant of the following message:

The authenticity of host 'github.com (192.30.255.112)' can't be established.

RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48. Are you sure you want to continue connecting (yes/no)?

It means that SSH has no information on the site, and wants you to verify the key fingerprint presented.

The key fingerprint (bolded above) could be different as GitHub uses two different keys, plus there are two different display formats.

You can find GitHub's SSH key fingerprint here. Ensure that what's shown matches one of them, and answer yes only when it does.

Create SSH Key

To create an SSH key, type in the following into your shell.

ssh-keygen -t rsa -b 4096 -C <type your email address here>

ssh-keygen will then walk you through a Q&A session to generate your SSH key file.

1. Enter file in which to save the key (<a default key position, something that ends in id_rsa):

If you just press ENTER when you see that, you'll save the key to the default location with the default file name of id_rsa.

The default locations for storing SSH related information is in the .ssh directory, which is located in your HOME directory (type echo $HOME in your shell to see where that is).

In Windows, it's /c/Users/<your user name>. In OS X, it's /Users/<your user name>, and in Linux it's /home/<your user name>. It's possible to change them.

So the default location of the file is $HOME/.ssh/id_rsa (for keys with the type of rsa, which we specified in the command with -t rsa).

It's fine if you only have a single server you need to SSH, but in this program we will be using multiple SSH keys, so it's best if you don't use the default name, and instead, name it something descriptive.

Usually that means using the hostname of the server you are accessing, so in this case it's github.com.

Type in the following:

<your home directory spelled out>/.ssh/<the new file name, such as github.com>

So if you are on Windows, it'd be:

/c/Users/<user name>/.ssh/github.com

You'll need to type out the full path, as it seems that ssh-keygen does not recognize any relative paths formats.

2. Enter passphrase (empty for no passphrase):

You can choose to password protect your key file, which will encrypt it and can only unlock with your password.

This will cause you to have to enter the password every time you use the key file, which kind of defeats the purpose of the key file in the first place. There is however a solution to this problem, and it involves the use of ssh-agent, and we will talk about it later.

If you choose no password, the key file will be unencrypted and will solely rely on your operating system's protection, so it means that you'll need to secure your development machine. This is usually a good enough solution, but it's of course your call of which way you go.

3. Enter same passphrase again:

Do the same as step 2. After this step your key file will be created and saved at the location you specified.

Upload SSH Key to GitHub

If you open the folder $HOME/.ssh, you'll see that there are two files created.

The reason is that rsa is an asymmetric encryption system, which has both a private key (which is <your key file>), and a public key (<your key file>.pub).

It's the content of the <your key file>.pub that we want to upload to GitHub.

  1. Copy the content of <your key file>.pub.
  2. Go to GitHub, ensure you are logged in, then go to Settings, and then go to SSH and GPG keys.
  3. Click on New SSH Key
  4. Give it a title (I usually name it to the development machine I'm using - yes I have separate SSH keys per machine as well),
  5. paste in the content of the file into the key field.
  6. Click Add SSH Key

You should be able to see a new key added to your GitHub account.

Configure Your SSH Client to Use the Key

As stated earlier that we will be using multiple SSH keys, the easiest way to do so is to create and use a SSH config file.

SSH Config file exist at the location of $HOME/.ssh/config, so we'll need to be sure that we save the file to that exact location.

Add the following to the SSH Config file and save.

Host github.com
    Hostname github.com
    User git
    IdentityFile ~/.ssh/<your key file>
    IdentitiesOnly yes

If you use empty password for your key file, now you can test access again:

ssh -T git@github.com

And you should see it succeed.

Configure SSH-Agent to reduce the need to type passwords (optional)

If you have chosen a password, you can still test but it'll prompt you for a password. To get rid of the prompting, you can now use ssh-agent.

eval $(ssh-agent -s)

Which will start the ssh-agent, and then you can add the key via:

ssh-add ~/.ssh/<your key file>

As this is per shell session, it means that you'll need to repeat the process if you were to open a new shell. To automate the process, you'll need to modify your .bash_profile (or .bashrc file) with the following:

if [ -z "$SSH_AUTH_SOCK" ] ; then
  eval `ssh-agent -s`
  ssh-add ~/.ssh/<your key file>
fi

So they will be run with every new shell session.