Using SSH keys with GitHub

1. Generate an SSH key-pair

First up, generate yourself an SSH key pair - unless you already have one you can reuse, in which case skip this step.

Notes on this step:

Replace anything in block caps below with something meaningful - it's just a comment that gets stored with the key to help you tell what it's used for in the future.
It will ask you if you want to password-protect (i.e. encrypt) the private half of the key pair. If you're using a Mac, I recommend you set a password as Git integrates with the MacOS keychain really nicely. I'm not familiar with how to setup 'transparent' password-protected private keys on other operating systems, so best to just set no password unless you know what you're doing.

ssh-keygen -t rsa -b 4096 -C "YOUR_NAME github key [email protected]" -f ~/.ssh/id_rsa_github

2. Ensure SSH key-pair permissions are correct

The next step is just to ensure that the ~/.ssh directory and the keys themselves have the correct permissions. These will almost certainly be correct already, but things can not work properly if they aren't set right. The most important thing here is that the private half of the key-pair you just made is only visible to you and not anyone else who might be sharing your computer.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa_github
chmod 644 ~/.ssh/id_rsa_github.pub

3. Configure SSH for the `github.com` host

Create the file ~/.ssh/config if it doesn't already exist, and open it for editing. You should add the following to it:

Host github.com
    User git
    UseKeychain yes
    IdentityFile ~/.ssh/id_rsa_github

4. Upload the public half of the key-pair to GitHub

Go to your settings section on GitHub, and then to the 'SSH and GPG keys' subsection. The URL should be: https://github.com/settings/keys. Click on the 'New SSH key' button, and add the content of the file ~/.ssh/id_rsa_github.pub, which is the public half of the key-pair you made in step 1.

5. Test you can authenticate to GitHub properly

Open up a terminal and enter the following:

ssh -T github.com

This should return a message that looks like this if everything is working correctly:

[10:17:13] ~ > ssh -T github.com
Hi robfraz! You've successfully authenticated, but GitHub does not provide shell access.

If the message it returns doesn't indicate you've authenticated successfully, then you've done something wrong. Sad times.

6. Clone repositories

With the setup described above, you can only clone repositories using SSH authentication - you will NOT be able to clone repositories using HTTPS. Thus, when you clone a repository, you'll have to use commands that look like this:

git clone github.com:YOUR_GITHUB_ACCOUNT_NAME/YOUR_REPOSITORY.git

If you already have some repositories that you've previously cloned with HTTPS, you'll have to go into the .git directory found within the repository and edit the config file to replace the remote URLs that start with https with ones that look like the above.

robfraz/using_ssh_keys_with_github.md