Guides: Providing your SSH Key

Overview

GitHub uses public-key cryptography and SSH to authenticate you during git’s push and pull commands. In order for GitHub to identify you, you must provide us with your SSH public key. The rest of this page contains instructions on how to locate or create a set of SSH keys.

• Mac OS X
• Linux
• Windows using msysGit
• Windows using PuTTYgen

Mac OS X

Step 1

Check to see if you already have a public/private key pair for your user. If you do, it will be in your ~/.ssh directory.

[~]$ cd .ssh
[~/.ssh]$ ls
config                id_dsa.pub
id_dsa                known_hosts

Key pairs are always named like something and something.pub. The something file is your private key and must be kept secret. The something.pub file is your public key, and this is what you’ll be giving us. If you already have a key pair (in the above listing I have an id_dsa key pair) and you want to use it for GitHub, then skip to Step 3.

Step 2

If you don’t have any keys yet, then you’ll need to generate them. This can be done with the ssh-keygen program.

[~/.ssh]$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/tom/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/tom/.ssh/id_rsa.
Your public key has been saved in /Users/tom/.ssh/id_rsa.pub.
The key fingerprint is:
50:43:77:c6:97:af:61:82:dc:ea:9b:6b:67:d4:1b:61 tom@volcano

The passphrase that you enter will be requested from you every time you push or pull from a private repo. You can use ssh-agent or the built-in keychain support in Leopard to automate password entry, or you can simply hit enter to not use a passphrase.

Note: you might need dsa key pair — see the troubleshooting section below.

Step 3

Copy your public key to the clipboard so you can easily paste it into your web browser.

[~/.ssh]$ cat id_rsa.pub | pbcopy

The pbcopy command copies whatever is sent to it via STDOUT to the clipboard, ensuring that you won’t have any extraneous newlines or other problems. Now you can simply select the appropriate text entry box in GitHub and paste in your public key! This text entry box can be found after logging in by clicking Account in the top right and looking under “SSH Public Keys”.

Problems?

The steps above didn’t work for me. I found that this openssh guide helped me out. The missing parts (i think) were:

1. `chmod 600 .pub’ after creation.
2. `ssh-add ’ in my shell.
3. the manual suggests `ssh-keygen -t dsa’ to generate the public and private keys. For some reasons, the rsa keys did not work for me on Mac OS X and Git 1.6.3. Regardless of the key type you use, whether dsa or rsa, watch carefully and update instructions accordingly i.e. replace id_dsa with id_rsa or vice verse if needed.

I debugged the connection by just trying a pure ssh connection to github:

`ssh -vi ~/.ssh/id_dsa git@github.com’

I needed to create a config file in the .ssh directory containing the following to point to the relevant IdentityFile:

Host github.com
  User git
  Port 22
  Hostname github.com
  IdentityFile ~/.ssh/id_dsa
  TCPKeepAlive yes
  IdentitiesOnly yes

Linux

Step 1: Check to see if you already have a public/private key pair for your user.

If you do, it will be in your ~/.ssh directory.

[~]$ cd .ssh
[~/.ssh]$ ls
config                id_dsa.pub
id_dsa                known_hosts

Step 2: Generate a public/private dsa key pair if you don’t already have one.

This is done with the ssh-keygen program:

[~/.ssh]$ ssh-keygen -t dsa
Generating public/private dsa key pair.
Enter file in which to save the key (/home/tom/.ssh/id_dsa): <enter>
Enter passphrase (empty for no passphrase): <enter passphrase or hit enter>
Enter same passphrase again: <enter passphrase again>
Your identification has been saved in /home/tom/.ssh/id_dsa.
Your public key has been saved in /home/tom/.ssh/id_dsa.pub.
The key fingerprint is: <hex string>

The passphrase that you enter will be requested from you every time you push or pull from a private repository. You can use ssh-agent to automate password entry, or you can simply hit enter to not use a passphrase.

Step 3: Upload your public key to GitHub.

Copy your public key to the clipboard so you can easily paste it into your web browser. If you have xclip installed then:

[~/.ssh]$ cat id_dsa.pub | xclip

The xclip command copies whatever is sent to it via STDIN to the clipboard (you may have to use xclip -selection clipboard), ensuring that you won’t have any extraneous newlines or other problems. Now you can simply select the appropriate text entry box in GitHub and paste in your public key! If you don’t have xclip then either install it using your OS’s package manager or print out the public key to a terminal so that you can manually copy the key data.

[~/.ssh]$ cat id_dsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA1FlHRbbxXIv/hLDTeJczlEqGNt0oFcoPEEENHThzP5ku
PDsitSSUH2MATP014G/3BzaI9pdnhf02MSEcmtmIKXrm05/dzxEmp9yOY32YHyk6/rLUGGTJuWOpGt3J
6H5LWxq9yeRUuFG/pCRH3+KxOyzasSHXfXJaC5v7wPxUdAeg9k0jwsUjnqUcYvzo5+GwCXV9dIwY3Sr/
OrL2l8SCdSWyd3PLufJXKQHlouHB0NI/+G/QjWmkB8c1PJh/VuIe36mqv82V9XXKvYNaVWwz5Sg6aY9u
p2lgDEme+AFdPPjOnkdF6OHCr7ymKg6c/B2YCbOW7QN/L4uAdVOhTNnJMQ== tom@volcano

Copy the entirety of the public key to the clipboard. It is important that there are no newlines in the key (copying from the cat output in your console should work properly. Now you can simply select the appropriate text entry box in your GitHub account and paste in your public key!

Microsoft Windows using msysGit

Step 1

Get the Git version of mysGit at: Git-(version).exe It’s a small download and installs just by double clicking the download. msysGit is a full featured environment for working with Git under windows.

Step 2

Run Git Bash program

Step 3

Then create a ssh key by typing:

ssh-keygen -C “username@email.com” -t rsa

Step 4

Look at the output and it will hint at where the key is stored. It’s stored in a .ssh folder somewhere, usually in your user folder c:\\Documents and Settings\\Username\\.ssh on XP or c:\\Users\\Username\\.ssh on Vista. The file with the public key is “id_rsa.pub”. Use windows search if you can’t find it. Then open it with notepad and copy the text. That is the public key you should add to your account on github. Leave the files where they are. Running ssh-keygen sets up the keys for both Git Bash and Git GUI that all come part of msysGit..

Microsoft Windows using PuTTYgen

We recommend most users use msysgit with openssh instead of putty. There seem to be fewer issues using openssh, as it is the default client.

If you don’t have any keys yet, then you’ll need to generate them. This can be done with the PuTTYgen tool, provided by the PuTTY project. There is also an installer available that includes all of the PuTTY tools.

1. Start PuTTYgen
2. Select SSH2 RSA or SSH2 DSA and press the “Generate” button.
3. PuTTYgen will prompt you to “generate some randomness by moving the mouse over the blank area”. Once this is done, a new public key will be displayed at the top of the window.
4. Enter a comment if you like, this will be used as the key’s “name” on GitHub if present
5. Enter a passphrase if you wish. Note that you will be asked for this passphrase every time you connect to GitHub. We only recommend using a passphrase if you are concerned other users may gain access to your keypair files.
6. Save the public and private keys somewhere. We recommend the openssh default: `/.ssh/id_rsa.pub` and `id_rsa` (or `id_dsa.pub` and `id_dsa` for a DSA pair)
7. Copy the public key and paste it into your GitHub account

You may wish to set up Pageant to manage your keys.