GitHub - Set up SSH Key

TLDR

Generate Key: ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Use descriptive name: /Users/[YourUser]/.ssh/github-[user]-[machine]

Set a passphrase: something-i-will-never-forget

Add to ssh-agent: eval "$(ssh-agent -s)" && ssh-add -K ~/.ssh/MY_KEY_NAME

Copy public key: pbcopy < ~/.ssh/MY_KEY_NAME.pub

Paste key at GitHub: Settings > SSH Keys > New SSH Key

The SSH protocol, allows you to securely connect and authenticate to remote servers and services. Setting up SSH keys on your GitHub account for each computer you work on, allows you to pull/push/commit without supplying your username or constantly typing your password.

To know more about SSH, see https://en.wikipedia.org/wiki/Secure_Shell

In this article, we'll go through the steps of generating a new SSH key on a Mac and registering it on your GitHub account. While I've done this more than I can count, I always have to check the steps so this article also serves as a quick future reference for me.

Do I have any SSH keys on this machine?

The following command lists the contents of the .ssh folder of the current user. SSH keys are just "plain" text files!

ls -al ~/.ssh

So how exactly can I generate an SSH key?

On your preferred Terminal app, run:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Next you'll be asked where to save the key:

> Enter a file in which to save the key (/Users/you/.ssh/id_rsa): [Press enter]

Since you'll probably have more than one key, it's better to not accept the default suggestion /Users/[YourUser]/.ssh/id_rsa and instead use something like:

/Users/[YourUser]/.ssh/github-[user]-[machine]

 

This will make it easier to know which key is used where.

We'll refer to the name chosen above for the SSH key as MY_KEY_NAME, in the rest of this article.

 

In my experience, the path entered needs to be absolute so you can't use ~/.ssh/some-key-name.

 

The rationale of using a generic id_rsa name is that you can have just one key that identifies this computer and you use that key on any services (GitHub, BitBucket, etc...) that you need to access. If at some point you need to revoke access to a certain service, you can delete the key on that service settings. (GitHub profile settings, etc...).

Personally I find it clearer to have specific keys for each service.

Lastly, you'll be prompted to enter a passphrase.

Enter passphrase (empty for no passphrase):

This allows securing your SSH key. While you can leave this empty (press ENTER) and not use a passphrase it's usually highly recommended. And by adding the key to ssh-agent via ssh-add we'll avoid having to type it constantly.

At this point, your new SSH key has been created.

You can see it by running the list command: ls -al ~/.ssh

You'll see two entries with MY_KEY_NAME. One is the private key which you should never share and the other, ending in .pub, is the public key, which you can use to gain access to remote services. Whenever you need to provide your SSH key, you always give the public key, never the private key.

Let's ensure the SSH agent "knows" about our new key and loads it automatically, which saves us from having to constantly re-type the passphrase.

Run each of the lines below in you terminal app:

eval "$(ssh-agent -s)" && ssh-add -K ~/.ssh/MY_KEY_NAME

We've finished generating a new SSH key, named it with a clear name that allows us to differentiate the keys in the future should we have more that one, and saved it to the ssh-agent so we don't need to constantly type the passphrase.

 

But GitHub has no knowledge of this key yet...

Hey GitHub, here's my new SSH key!

Start by copying the public key (note the ending .pub) to the clipboard so we can paste it at GitHub's dashboard:

pbcopy < ~/.ssh/MY_KEY_NAME.pub

Now go to your GitHub account Settings > SSH Keys. At the time of writing the URL is https://github.com/settings/keys and click the button New SSH Key.

You'll see a form with two fields:

• Title: Enter a descriptive name for this key. Ex: My Work Mac
  
  it's important to use a clear title as it's what will allow you to know which key is used where and as such know which ones can/should be deleted.

• Key: Hit CMD+V to paste the SSH public key copied above.
  
  it should be a long string that starts with ssh-rsa ... and ends with the email address entered when the key was created.

Yay! All done!

Hope this article has been useful for you.

Any amends or suggestions are welcome in the comments below.