Using Git with GitHub

To be able to push or pull repositories to or from GitHub, you will have to set up a secure link with it first. The following steps walk you through configuring Git and connecting it to GitHub on your computer. [These instructions are adapted from GitHub’s documentation.]

These directions, and your work in most classes, will make frequent (nearly constant) use of the Unix command line. To learn, refresh, or look up information on how to use the command line, check out the resources in Unix and the Command Line. Command line proficiency will be critical for making progress on this and later work.

Initial Setup

These instructions assume you already have Git installed and working in a Unix command line environment.

Before you run any other Git commands, you should first tell it who you are. It needs this information to assign an “author” to new commits. Run the following commands with your own name and email address:

git config --global user.name "Your Name"

git config --global user.email "emailaddress@example.com"

Check for Existing Keys

Connecting to GitHub will require a pair of SSH keys (aka a “key pair”): a public key that you share with GitHub and a private key kept on your computer. Git will use public-key encryption to authenticate you to GitHub using these keys.

First, check if you have any existing SSH keys on the system you’re using by listing the files in your .ssh directory:

ls -la ~/.ssh/

If you see a file named id_rsa.pub, id_ecdsa.pub, or id_ed25519.pub, you have an existing key pair. You can then skip the next step (creating a new key pair).

If you do not see any files with those names or if you see an error saying that ~/.ssh/ does not exist, then go to the next step to create a key pair.

Generate a New Key

To create a new public/private key pair, run this command with the same email address you configured earlier:

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

This will create a new key pair in your ~/.ssh/ directory.

It will ask you to enter a filename for the new key. You can press enter to accept the default location.

It will then ask you to enter a “passphrase.” You can leave this blank by pressing enter, or you can enter a passphrase that must be provided to use the key you generate every time you connect via SSH. If creating this key on a shared computer, it is wise to use a passphrase to secure the key. On your own computer, you can choose either way.

(If you do create the key with a passphrase, you can use ssh-agent to avoid having to enter your passphrase every time you use the key, but its setup is beyond the scope of these instructions. GitHub’s documentation can help if you want to go that way.)

Add your Key to your GitHub Account

To authenticate with GitHub over SSH, you need to provide the public key of your key pair to GitHub. (The private key should never leave your computer.)

  1. Go to your GitHub account settings by finding Settings in the menu under your profile picture in the upper-right of any GitHub page.

  2. In the “Access” section of the options on the left, go to SSH and GPG keys.

  3. Click New SSH Key to get to a form where you can provide the new key.

  4. In the “Title” field, write a descriptive label for the key. I often name the computer on which I created and will use the key.

  5. Leave the “Key type” as “Authentication Key.”

  6. Get the contents of your public key from a terminal by running cat ~/.ssh/id_ed25519.pub (or whatever filename your public key is saved under, if different), then select the full contents of the file displayed by that command, copy it, and paste it into the “Key” textarea in your browser.

  7. Save the key by pressing Add SSH key.

Test your SSH Connection

If everything has gone well, then you should be able to connect to GitHub via SSH:

ssh -T git@github.com

The first time you connect, you will probably see a warning about how “the authenticity of the host can’t be established.” This is fine. (If you’re concerned about an attacker compromising your connection to GitHub, you can verify the key fingerprint you see by comparing it to GitHub’s published fingerprints.) Type yes to proceed.

You should then see:

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

If you see that, you’ve successfully registered your SSH key and connected to GitHub. That’s it!

If you do not see the “successfully authenticated” message, something went wrong in an earlier step (or maybe you skipped one). Ask for help!

modified: