🔀 Merge pull request #271 from carpentries-incubator/issue-243

Improved wording around SSH and key authn with GitHub

_episodes/11-software-project.md

@@ -60,8 +60,10 @@ from GitHub within your own GitHub account
 and then obtain a local copy of that project (from your GitHub) on your machine.
 
 1. Make sure you have a GitHub account
-   and that you have set up your SSH key pair for authentication with GitHub,
+   and that you have set up your **SSH key pair for authentication with GitHub**,
    as explained in [Setup](../setup.html#secure-access-to-github-using-git-from-command-line).
+   Note that, while it is possible to use **HTTPS** with a personal access token for authentication with GitHub,
+   the recommended and supported authentication method to use for this course is via SSH and key pairs.
 2. Log into your GitHub account.
 3. Go to the [software project template repository](https://github.com/carpentries-incubator/python-intermediate-inflammation)
    in GitHub.
@@ -99,8 +101,8 @@ and then obtain a local copy of that project (from your GitHub) on your machine.
 > > 1. Find the SSH URL of the software project repository to clone from your GitHub account.
 > > Make sure you do not clone the original template repository but rather your own copy,
 > > as you should be able to push commits to it later on.
-> > Also make sure you select the **SSH tab** and not the **HTTPS** one -
-> > you'll be able to clone with HTTPS, but not to send your changes back to GitHub!
+> > Also make sure you select the **SSH** tab and not the **HTTPS** one -
+> > for this course, SSH is the preferred way of authenticating when sending your changes back to GitHub.
 > >
 > > ![URL to clone the repository in GitHub](../fig/clone-repository.png){: .image-with-shadow width="800px" }
 > >

_episodes/14-collaboration-using-git.md

@@ -259,41 +259,34 @@ $ git pull
 {: .language-bash}
 
 Now we've ensured our repository is synchronised with the remote one,
-we can now push our changes.
-GitHub has recently
-[strengthened authentication requirements for Git operations](https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/)
-accessing GitHub from the command line over HTTPS.
-This means you cannot use passwords for authentication over HTTPS any more -
-you either need to
-[set up and use a personal access token](https://catalyst.zoho.com/help/tutorials/githubbot/generate-access-token.html)
-for additional security if you want to continue to use HTTPS,
-or switch to use private and public key pair over SSH
-before you can push remotely the changes you made locally.
-So, when you run the command below:
+we can now push our changes:
 
 ~~~
 $ git push origin main
 ~~~
 {: .language-bash}
 
-> ## Authentication Errors
+In the above command,
+`origin` is an alias for the remote repository you used when cloning the project locally
+(it is called that by convention and set up automatically by Git
+when you run `git clone remote_url` command to replicate a remote repository locally);
+`main` is the name of our main (and currently only) development branch.
+
+> ## GitHub Authentication/Authorisation Error
 >
-> If you get a warning that HTTPS access is deprecated, or a token is required,
-> then you accidentally cloned the repository using HTTPS and not SSH.
-> You can fix this from the command line by
-> resetting the remote repository URL setting on your local repo:
+> If, at this point (i.e. the first time you try to write to a remote repository on GitHub), 
+> you get a warning/error that HTTPS access is deprecated, or a personal access token is required,
+> then you have cloned the repository using HTTPS and not SSH.
+> You should revisit the [instructions 
+> on setting up your GitHub for SSH and key pair authentication](../setup.html#secure-access-to-github-using-git-from-command-line)
+> and can fix this from the command line by
+> changing the remote repository's HTTPS URL to its SSH equivalent:
 >
 > ~~~
 > $ git remote set-url origin git@github.com:<YOUR_GITHUB_USERNAME>/python-intermediate-inflammation.git
 > ~~~
 > {: .language-bash}
-{: .caution}
-
-In the above command,
-`origin` is an alias for the remote repository you used when cloning the project locally
-(it is called that by convention and set up automatically by Git
-when you run `git clone remote_url` command to replicate a remote repository locally);
-`main` is the name of our main (and currently only) development branch.
+{: .callout}
 
 >## Git Remotes
 > Note that systems like Git allow us to synchronise work between

setup.md

@@ -121,27 +121,40 @@ GitHub is a free, online host for Git repositories that you will use during the
 you will need to open a free [GitHub](https://github.com/) account unless you don't already have one.
 
 ### Secure Access To GitHub Using Git From Command Line
-In order to access GitHub using Git from your machine securely, you need to set up a way of authenticating yourself 
-with GitHub through Git. The recommended way to do that for this course is to set up 
-[*SSH authentication*](https://www.ssh.com/academy/ssh/public-key-authentication) - a 
-method of authentication that is more secure than sending [*passwords over HTTPS*](https://security.stackexchange.com/questions/110415/is-it-ok-to-send-plain-text-password-over-https) and which requires a pair of keys - one public that you 
-upload to your GitHub account, and one private that remains on your machine. 
+
+In order to access GitHub using Git from your machine securely,
+you need to set up a way of authenticating yourself with GitHub through Git.
+The recommended way to do that for this course is to set up
+[*SSH authentication*](https://www.ssh.com/academy/ssh/public-key-authentication) -
+a method of authentication that is more secure than sending
+[*passwords over HTTPS*](https://security.stackexchange.com/questions/110415/is-it-ok-to-send-plain-text-password-over-https)
+and which requires a pair of keys -
+one public that you upload to your GitHub account, and one private that remains on your machine.
 
 GitHub provides full documentation and guides on how to:
 - [generate an 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), and
 - [add an SSH key to a GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
 
 A short summary of the commands you need to perform is shown below.
 
-To generate an SSH key pair, you will need to run the `ssh-keygen` command from your command line tool/GitBash 
-and provide **your identity for the key pair** (e.g. the email address you used to register with GitHub) 
-via the `-C` parameter as shown below. Note that the `ssh-keygen` command can be run with different 
-parameters - e.g. to select a specific public key algorithm and key length; if you do not use them `ssh-keygen` will generate an [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)#:~:text=RSA%20involves%20a%20public%20key,by%20using%20the%20private%20key.) key pair for you by default. It will also prompt you to answer a few questions - e.g. where to save the keys on your machine and 
-a passphrase to use to protect your private key. Pressing 'Enter' on these prompts 
-will get `ssh-keygen` to use the default key location (within `.ssh` folder in your home directory) and set the passphrase to empty.
+To generate an SSH key pair, you will need to run the `ssh-keygen` command from your command line tool/GitBash
+and provide **your identity for the key pair** (e.g. the email address you used to register with GitHub)
+via the `-C` parameter as shown below.
+Note that the `ssh-keygen` command can be run with different parameters -
+e.g. to select a specific public key algorithm and key length;
+if you do not use them `ssh-keygen` will generate an
+[RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)#:~:text=RSA%20involves%20a%20public%20key,by%20using%20the%20private%20key.)
+key pair for you by default.
+GitHub now recommends that you use a newer cryptographic standard,
+so please be sure to specify the `-t` flag as shown below.
+It will also prompt you to answer a few questions -
+e.g. where to save the keys on your machine and a passphrase to use to protect your private key.
+Pressing 'Enter' on these prompts will get `ssh-keygen` to use the default key location (within
+`.ssh` folder in your home directory)
+and set the passphrase to empty.
 
 ~~~
-$ ssh-keygen -C "your-github-email@example.com"
+$ ssh-keygen -t ed25519 -C "your-github-email@example.com"
 ~~~
 {: .language-bash}
 ~~~