SSH keys are used to authenticate your computers without having to enter a password every time you initiate a connection. In order for your computer to be able to communicate with your remote repos like GitHub or BitBucket, you need to setup an SSH key on your local machine, and upload that key to your Git Host. You'll also need to create an SSH key on any servers that need to access your repositories, such as your live server and dev or staging servers.

Check for an Existing SSH Key

Before you generate a new SSH key, it's a good idea to check for an existing key first. If one already exists, you can choose to use that key instead of creating a new one.

To check for existing keys:

  • Open your terminal application
  • (If you're checking your server, ssh into your account)
  • Type "ls -al ~/.ssh" and press Enter

If you see a list of files, with the file "id_rsa.pub" in the list, you already have an SSH key setup, and can skip to the "Add Your SSH Key to Your Account" section for the git host that you choose to use.

If instead, you get a message that says "No such file or directory", you need to generate an SSH key in order to continue.

Generate a New SSH Key

Note: The following instructions are to be performed on your local machine. You may also need to follow these instructions on your web host, but only if you don't have a control panel, which most servers do. Check with your host for the proper way to create SSH Keys on their platform.

To generate a new SSH key, type the following into your terminal:

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

This invokes the ssh key generator, specifies to use the rsa key type, and uses your email address as the key label.

When you do that, you'll see this series of prompts

  • Enter file in which to save the key (/Users/USERNAME/.ssh/id_rsa): (The default location is the .ssh directory in your user directory. This is the preferred location, so just press Enter.)
  • Enter passphrase (empty for no passphrase): (You definitely want to set a passphrase, so type one in and press Enter. If you're not familiar with typing passwords in the terminal, it will appear that nothing is happening when you type your password. It is recording what you type though, so type as normal.)
  • Enter same passphrase again: (Type the same passphrase and press Enter.)

When you're finished, you'll see a message like this:

Your identification has been saved in /Users/USERNAME/.ssh/id_rsa.
Your public key has been saved in /Users/USERNAME/.ssh/id_rsa.pub.
The key fingerprint is:
01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db your_email@example.com

You may also see a line that says "The key's randomart image is:" we don't need to use that, so you can ignore it.