Key; 19th century, after 17th century original; British, after Italian original. New York Metropolitain Museum of Art Object Number: 83.18.291
Arduino Development, Coding, How To

Using SSH in GitHub on Windows

A while back GitHub moved to requiring SSH authentication for checkins. I was puzzled and put off for a long time because the Git instructions about SSH cover every case rather than being a “do this and it will work for GitHub on Windows.”

These notes describe how I set up and use SSH with GitHub.

One-Time Setup to Run ssh-agent

Most of the steps below require ssh-agent to be running. You can automatically start ssh-agent when you open a Git Bash shell.

Add the following text to your ~/.bash_profile file, creating the file if it doesn’t exist.

env=~/.ssh/agent.env

agent_load_env () { test -f "$env" && . "$env" >| /dev/null ; }

agent_start () {
    (umask 077; ssh-agent >| "$env")
    . "$env" >| /dev/null ; }

agent_load_env

# agent_run_state: 0=agent running w/ key; 1=agent w/o key; 2=agent not running
agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?)

if [ ! "$SSH_AUTH_SOCK" ] || [ $agent_run_state = 2 ]; then
    agent_start
    ssh-add
elif [ "$SSH_AUTH_SOCK" ] && [ $agent_run_state = 1 ]; then
    ssh-add
fi

unset env

Now whenever you run Git Bash, the first thing it will do is to automatically run ssh-agent.

One-Time SSH Key creation on your Windows PC

Create a new SSH key that you’ll use whenever you checkin on GitHub:

  1. Open Git Bash
  2. Type ssh-keygen -t ed25519 -C "YOUREMAIL" replacing YOUREMAIL with the email address you use to login to GitHub.
  3. keygen will prompt you for a filename for the created private key. I used ~/.ssh/github
  4. keygen will then prompt you for a passphrase. If you want to protect your keys with a passphrase, which you enter each time you start Git Bash and each time you do a GitHub commit, enter it here. Otherwise leave it blank.
  5. keygen will prompt you to reenter the passphrase. If you decided not to have one, just hit the Enter key.
  6. type ssh-add ~/.ssh/YOURKEY replacing YOURKEY with the name you gave keygen.

Next, you’ll tell GitHub about that key:

  1. Still in Git Bash, type cat <~/.ssh/YOURKEY.pub replacing YOURKEY wi the name you gave keygen. This action copies the public key to the clipboard.
  2. In a browser, open github.com and log in.
  3. On the GitHub page, click your profile icon (in the upper right of the page).
  4. Click settings
  5. In the resulting page, click on SSH and GPG keys
  6. On the resulting page, under SSH keys, click the button marked New SSH key.
  7. On the resultant page, for Title, type a name for this key. I use a name to indicate what PC the key was generated on, for example 2025-laptop
  8. Under Key Type, select Authentication Key
  9. Under Key, paste from the clipboard. The key should start with something like ‘ssh’ and end with your email. If that’s not what was on the clipboard, go back to the Git Bash window and re-run the clip command, then paste here.
  10. Click Add SSH key
  11. You might need to re-authenticate with GitHub, using your 2nd-factor authentication, for example a Microsoft Authenticator code, that I describe in Using Microsoft Authenticator with GitHub.

Now GitHub knows that your PC’s github key can be used to authenticate your checkins from here on.

GitHub checkin/checkout Using Your SSH Key

When you are ready to either checkout or checkin a project on GitHub follow these instructions.

Suppose you want to check out my personal Weather Underground thermometer project, bneedhamia/MAX31820WeatherStation:

  1. On your PC, start Git Bash.
  2. Browse to the repository that you want to clone, such as https://github.com/bneedhamia/MAX31820WeatherStation
  3. On that page, click the Code button.
  4. In the dropdown, click on the SSH tab
  5. Click the Copy Url to Clipboard icon, to the right of the url.
  6. In Git Bash…
  7. cd to the folder you want to clone into. For Arduino projects, I use Documents/Arduino.
  8. type git clone then paste from the clipboard. The pasted url should start with git@github.com

You should now have a copy of the project.

When you’re finished testing your changes, do the normal Git Bash commands to commit and push the project. Your SSH key will be used invisibly in the background. If you have a passphrase you will be prompted to type it in.

Removing your GitHub SSH key

If for some reason things aren’t working and you want to start over setting up GitHub’s SSH checkin/checkout, do the following steps:

First, remove your key(s) from GitHub:

  1. On your PC, browse to github.com and login.
  2. On the GitHub page, click your profile icon (in the upper right of the page).
  3. Click settings
  4. In the resulting page, click on SSH and GPG keys
  5. Find the authentication key you are using and click its delete button.

Next, remove your key from the ssh-agent:

  1. On your PC, start Git Bash
  2. in Git Bash, type ssh-add -l (that’s a lower-case L)
  3. Note, in the output, the name in parentheses. For example (ED25519)
  4. Construct a full path to that private key file. For example, mine is ~/.ssh/id_ed25519
  5. in Git Bash, type ssh-add -d ~/.ssh/id_YOURNUMBER (for example ssh-add -d ~/.ssh/id_ed25519

Now neither GitHub nor your PC know about the deleted key.

References

The Git pages are thorough and, after all is said and done, relatively easy to follow. My notes are distilled from these pages:

Comments? Corrections? Join the conversation on BlueSky, or through any of the contact links on the upper-left of this Post.

Featured Image: "Key"; 19th century, after 17th century original; British, after Italian original; Courtesy of the New York Metropolitain Museum of Art