GitHub CLI as an alternative to manual `ssh` key generation

[Will Graham]

There's been several discussions (#857, #908 and related #895) concerning how the SSH keys portion of the git-novice lesson has proven to be quite distracting and confusing for learners, particularly if they have only just been introduced to the command-line in the previous lesson.

In September we taught the Git lesson and got learners to install GitHub CLI on their machines as part of the setup instructions. Whilst this does rely on users having install rights on the machine they're using, (and to a lesser extent is a tool specific to GitHub) it was very effective at simplifying the key-generation portion of the lesson. Learners could run:

gh auth login

in their terminal, and the program asks them a series questions of how they want to connect to the remote, which requires the following details:

1. Their account on GitHub
2. The protocol they want to use (ssh)
3. Whether to generate a new SSH key (yes)
4. A new password for connecting to GitHub (make sure they write this down!)
5. Title for the key
6. How to authenticate the key: we suggested using the web browser option, which does the following:
7. Shows a “one-time code”. Learners can then press enter to open a browser and enter this code, and should get a message saying “you have authenticated” with a green tick.

Users seemed much happier with answering these questions and having the CLI do the setup-work under the hood. We also provided some suggestions for the fields like "key title" etc, to streamline the process and make troubleshooting easier. They can then link their remote repositories to their local ones in the usual manner.

This did require a slight modification on our part to the setup instructions, and also meant a large chunk of the remotes on GitHub lesson was redundant. However for the purposes of streamlining the setup so that we could get onto the collaborating portion of the lesson - which I would argue is a more important aspect of the lesson than learning about ssh keys - it seemed to work very well.

[Daniel McCloy]

+1. I've heard similar anecdote from @SJaffa, and I just tried out the gh auth login for the first time myself yesterday (having just taught the git lesson last week, so the pain of teaching the SSH setup is still fresh in my mind). I don't think the learners minded the SSH part --- there were several questions and I think some of them were able to connect some dots in their head about how connections to remote computers work --- but I'm confident that the gh auth login approach would have been faster, leaving more time for stuff that we didn't have time to cover (stuff that, I'd argue, is more important than a fairly shallow understanding of how SSH works). TL;DR: it's OK if SSH is "magic" and under-the-hood; the time and learner effort savings is worth it.

[K.E. Koziar]

@willGraham01 @drammock thank you for the feedback. There have been long discussions regarding SSH vs PAT. The end result is the git lesson inherited it because the Unix Shell maintainers suggested the best example for using it is git. We did decide to include more rather than less, so an instructor can determine what they have time to go over. And, many people agreed that SSH is better than PATs, because SSH is used more widely (and often in command line situations, not just for git).

There is a supplemental SSH episode still in development which includes PATs. Please feel free to contribute. Issue #824 describes how to contribute.

[K.E. Koziar]

@willGraham01 as an additional point, and specifically on GitHub CLI, the lesson (and Carpentries lessons) tend towards general solutions, and not those available only on a particular platform. This is why the lesson doesn't cover github desktop, since we're teaching git, and not github.