Add section on GitHub authentication (#68)

* add new section on SSH keys

* Include SSH key references

* Update section links on page footer

* Match the GitHub documentation headings

* Windows app is now Git Bash

* Update git remotes diagram

* Text edits + add section link

* Text edits, update remotes to use SSH

lessons/git/configuring-git.md

@@ -6,7 +6,7 @@ When using `git` for the first time on a computer,
 some setup is required.
 Start by opening a terminal
 (your preferred terminal app on Linux or macOS;
-the Git Bash Shell on Windows).
+Git Bash on Windows).
 
 Make sure `git` is installed and in the application search path:
 ```
@@ -93,4 +93,4 @@ ___
 
 [Introduction to version control](./index.md) |
 Previous: [index](./index.md) |
-Next: [A version control workflow](./git-workflow.md)
+Next: [GitHub authentication](./github-authentication.md)

lessons/git/git-workflow.md

@@ -3,13 +3,12 @@
 # A version control workflow
 
 In this section,
-we'll work through an example that broadly demonstrates
+we'll work through a long-ish example that demonstrates
 how to use version control on an individual or a group project.
-Imagine, for example,
+Imagine, for instance,
 backing up and tracking your thesis,
-or collaborating on a journal article
+or collaborating on writing a journal article
 with a colleague.
-<!-- This is where GitHub is powerful. -->
 
 We'll broadly follow the series of actions in this workflow:
 
@@ -66,13 +65,15 @@ On your computer, open a terminal and change to your **Desktop** directory:
 ```
 $ cd ~/Desktop
 ```
+Note that this is a convenience; you can do the following steps anywhere on the filesystem.
 
 Now clone your repository from GitHub.
 The syntax for the `git clone` subcommand is
 ```
 $ git clone [repository-url]
 ```
-where the bracketed text should be replaced with the URL of your new repository.
+where the bracketed text should be replaced with the SSH URL of your new repository.
+You'll be prompted to enter the password for your SSH key.
 
 The repository is cloned into the directory **ivy-collaboration**.
 Change to it and view its contents:
@@ -165,13 +166,13 @@ In this example, however, it'll be trivial.
 
 Recall that the **ivy-collaboration** repository
 has a file, **CONTRIBUTORS.md**.
-View the contents of the repository:
+View the files in the repository:
 ```
 $ ls
 CONTRIBUTORS.md LICENSE   README.md
 ```
 With your favorite text editor,
-open the file **CONTRIBUTORS.md**
+open **CONTRIBUTORS.md**
 add your name to the list of contributors,
 along with something interesting
 (but not too interesting--this is a public repository).
@@ -316,6 +317,7 @@ remote:
 To https://github.com/mdpiper/ivy-collaboration
  * [new branch]      mdpiper/update-contributors -> mdpiper/update-contributors
 ```
+You'll again be prompted to enter the password for your SSH key.
 
 Note that the output from `git push`
 includes a link to create a *pull request* on GitHub.
@@ -375,24 +377,24 @@ We can *sync* these repositories in a few steps.
 First,
 use the `git remote` subcommand to view what remotes are being tracked on your local machine:
 ```
-origin	https://github.com/mdpiper/ivy-collaboration (fetch)
-origin	https://github.com/mdpiper/ivy-collaboration (push)
+origin	git@github.com:mdpiper/ivy-collaboration.git (fetch)
+origin	git@github.com:mdpiper/ivy-collaboration.git (push)
 ```
 
 By default,
 the only remote tracked is *origin*.
 We can track the *upstream* remote, as well, with:
 ```
-$ git remote add upstream https://github.com/csdms/ivy-collaboration
+$ git remote add upstream git@github.com:csdms/ivy-collaboration.git
 ```
 
 Check the result with another call to `git remote`:
 ```
 $ git remote -v
-origin	https://github.com/csdms/ivy-collaboration (fetch)
-origin	https://github.com/csdms/ivy-collaboration (push)
-upstream	https://github.com/csdms/ivy-collaboration (fetch)
-upstream	https://github.com/csdms/ivy-collaboration (push)
+origin	git@github.com:mdpiper/ivy-collaboration.git (fetch)
+origin	git@github.com:mdpiper/ivy-collaboration.git (push)
+upstream	git@github.com:csdms/ivy-collaboration.git (fetch)
+upstream	git@github.com:csdms/ivy-collaboration.git (push)
 ```
 
 Next, switch back to the *main* branch in your local repository.
@@ -470,4 +472,4 @@ This table summarizes the `git` subcommands used in this section:
 ___
 
 [Introduction to version control](./index.md) |
-Previous: [Version control in a single-user project](./git-single-user-project.md)
+Previous: [GitHub authentication](./github-authentication.md)

lessons/git/github-authentication.md

@@ -0,0 +1,120 @@
+![Ivy logo](https://raw.githubusercontent.com/csdms/ivy/main/media/logo.png)
+
+# GitHub authentication
+
+GitHub allows users to connect to remote repositories
+through two protocols, HTTPS and SSH.
+
+When using HTTPS,
+a user must supply a personal access token (PAT)--a long string of characters--on
+every connection attempt.
+
+When using SSH,
+GitHub looks for an SSH key cached locally.
+An SSH key is a little harder to set up than a PAT,
+but easier to use over time.
+
+In this lesson,
+we'll cover how to create an SSH key
+and add it to your GitHub profile.
+
+## Check for an existing SSH key
+
+Before we create a new SSH key,
+let's check if you already have one on your system.
+Open a terminal and type
+```
+$ ls ~/.ssh
+```
+
+GitHub supports three types of keys.
+If you have a **.ssh** directory with one of these files:
+
+* **id_rsa.pub**
+* **id_ecdsa.pub**
+* **id_ed25519.pub**
+
+you can skip ahead to the [Add an SSH key to GitHub](./github-authentication.md#add-an-ssh-key-to-github) section.
+
+If you don't have a **.ssh** directory
+or one of the three supported key types,
+proceed to the next section.
+
+## Create an SSH key
+
+To create a new SSH key,
+type the following into a terminal:
+```
+$ ssh-keygen -t ed25519 -C "[your email address]"
+```
+The `-t` flag specifies the type of key to create;
+in this case,
+using the [ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) algorithm.
+Use the email address associated with your GitHub account.
+Follow the prompts and enter a password.
+
+Check the contents of your **.ssh** directory (which will now exist if it didn't before):
+```
+$ ls ~/.ssh
+id_ed25519      id_ed25519.pub
+```
+You now have an SSH key pair (private, public).
+
+Remember your password!
+You'll have to enter it when connecting to GitHub.
+Optionally,
+you can use the `ssh-agent` service on your computer to store the password;
+GitHub provides [documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) for doing so.
+
+## Add an SSH key to GitHub
+
+Now that we have an SSH key pair,
+we need to add the public key to GitHub.
+
+Start by copying the public key.
+Print the key to the terminal with `cat`:
+```
+$ cat ~/.ssh/id_ed25519.pub
+ssh-ed25519 AA4WC3NzqC45ZD81NTR5AQAAIBbFO9USDsVFLRIiBJ9Y6wJil4AFrW5ysRrGNCd5wDvy mark.piper@colorado.edu
+```
+then select the text and copy it.
+
+Next, go to https://github.com/settings/keys.
+(If you aren't signed in to GitHub,
+you'll be prompted to do so.)
+
+In the "SSH keys" section,
+click the *New SSH key* button.
+In the resulting form,
+you can name your key
+and paste in the key text.
+
+That's it!
+
+## Test your SSH key
+
+To check that GitHub has your SSH key, type the following in terminal:
+```
+$ ssh -T git@github.com
+```
+You'll be prompted to enter the password for your key.
+
+If you get a return like
+```
+Hi mdpiper! You've successfully authenticated, but GitHub does not provide shell access.
+```
+you're all set!
+
+## Summary
+
+Github requires either a personal access token (PAT)
+or an SSH key
+to connect to remote repositories.
+Here,
+we describe how to create and add an SSH key to GitHub.
+
+___
+
+[Introduction to version control](./index.md) |
+Previous: [Configuring git](./configuring-git.md)
+Next: [A version control workflow](./git-workflow.md)

lessons/git/index.md

@@ -50,12 +50,18 @@ Here are some examples...
 This lesson on version control continues in the following sections.
 
 1. [Configuring git and GitHub](./configuring-git.md)
+1. [GitHub authentication](./github-authentication.md)
 1. [A version control workflow](./git-workflow.md)
 
 
 ## Resources
 
 * Software Carpentry [lesson](https://swcarpentry.github.io/git-novice/) on version control
 * A [git command cheatsheet](https://education.github.com/git-cheat-sheet-education.pdf) from GitHub
+* [Secure shell (SSH)](https://en.wikipedia.org/wiki/Secure_Shell) description on Wikipedia
+* In the GitHub documentation:
+  * [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+  * [Generating a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
+  * [Adding a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)
 * The full [git documentation](https://git-scm.com/docs)
 * The full [GitHub documentation](https://docs.github.com)