Using Git with SSH

Based on our experience with the GitHub Personal Access Tokens (PATs) during CAPP Camp, we have decided to switch to using Git with SSH. This document contains the information necessary to get set up to use Git with SSH on the departmental Linux servers.

Where should you do this lab?

You’ll be doing this lab on personal laptop in your first discussion section. You will need to connect to the Linux servers:

  • using the Department’s virtual desktop system,

  • using VSCode with SSH integration, or

  • by connecting to a CS server using SSH.

The CS techstaff provides detailed instructions on how to connect to a CS server using SSH.

Creating an SSH Key

When you log into the GitHub website, you will use the username and password associated with your GitHub account. However, when using Git commands from the terminal, things are a bit different. In particular, GitHub uses two mechanisms for authenticating yourself from the terminal: Personal Access Tokens and SSH Keys. We have decided to switch to using SSH keys based on our experience with the PATs during CAPP Camp.

In a nutshell, an SSH key is a file that resides in your home directory, and which you can think of as a file that stores a secure password (SSH keys are a bit more complex than that but, for our purposes, we can just think of them as extra-secure passwords)

To create an SSH key, run the following command from the Linux command-line:

$ ssh-keygen

You will see the following prompt:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):

Press Enter (this will select the default file path shown in the prompt: /home/username/.ssh/id_rsa

Note

If, after pressing Enter, you see the following message:

/home/username/.ssh/id_rsa already exists.
Overwrite (y/n)?

This means there is already an SSH key in your home directory. You should proceed as follows:

  1. If you are already familiar with SSH keys, and know for certain that you’d like to use your existing SSH key, type “n” and skip ahead to the “Uploading your SSH key to GitHub” section below.

  2. If you do not know why you have an SSH key in your directory, it’s possible it was created for you if you’ve taken another CMSC class in the past. Type “n” and then run the following commands to create a backup of your existing key:

    mv ~/.ssh/id_rsa ~/.ssh/id_rsa.bak
mv ~/.ssh/id_rsa.pub ~/.ssh/id_rsa.pub.bak

    Then, re-run the ssh-keygen command and follow the rest of the instructions in this section.

Next, you will see this prompt:

Enter passphrase (empty for no passphrase):

Just press Enter here. You will be asked to confirm (just press Enter again):

Enter same passphrase again:

Note

While it may seem counterintuitive, we don’t want our SSH key to have a passphrase (this is an added layer of security which we won’t need for this class; your GitHub account will still be secure even if your SSH key doesn’t have a password)

If all goes well, you should see something like this:

Your identification has been saved in /home/username/.ssh/id_rsa
Your public key has been saved in /home/username/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:cBUUs2FeMCIrBlTyv/PGpBtNz0v235zvLykpoWIOS9I username@machine
The key's randomart image is:
+---[RSA 3072]----+
| .+.. . ..@+.    |
|   +   o = *     |
|    + o . o      |
|   . o o         |
|      . S        |
|   .   +.o.      |
|  . E ++..=. . . |
|   o o+++o.oo oo.|
|    .oo+. ...o.+O|
+----[SHA256]-----+

This means your key was created correctly.

Uploading your SSH key to GitHub

Now, we need to instruct GitHub to accept our SSH key. To do this, log into https://github.com/ and go to your Settings page (by clicking on the top-right account icon, and then selecting “Settings” in the drop-down menu. Then, click on “SSH and GPG keys”.

Now, click on the green “New SSH key” button. This will take you to a page where you can upload your SSH key. You will be asked for two values: a “Title” and the key itself. The title can be anything you want, but we suggest something like “CS Server SSH Key”.

The value of the key is contained in the .ssh/id_rsa.pub file in your home directory. To print out the contents of that file, we can just use the cat command, which we covered in the Linux tutorial:

$ cat ~/.ssh/id_rsa.pub

This will print a few lines of output starting with ssh-rsa and ending in something like username@machine. Copy the whole output to the clipboard; you can do this by clicking and dragging the mouse from the first character to the last character, and then pressing Ctrl-Shift-C. If Ctrl-Shift-C does not work try using your machine’s standard text copy and paste mechanism.

Then, paste the key into the “Key” field on the GitHub page. Then click on the green “Add SSH Key” button.

To verify that you correctly uploaded the key, try running the following command:

ssh -T git@github.com

You may see a message like this:

The authenticity of host 'github.com (...)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no)?

You can safely enter “yes” here. You should then see a message like this:

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

This means your SSH key is properly set up (don’t worry about the “does not provide shell access”; that is normal).

If you are unable to set up your SSH key, please make sure to ask for help.

If you would like to set up SSH access from your personal computer at a later time, GitHub provides some pretty detailed documentation on how to do this in a number of different operating systems: Connecting to GitHub with SSH Please note that we may not be able to assist you with SSH issues on your own computer.

Acknowledgments

Borja Sotomayor put together these instructions.