Experiences/issues with new SSH key material

[jcohen02]

This issue relates to episode 7 of the Git lesson "Remotes in GitHub" - specifically, the "SSH Background and Setup" part of the material.

At a recent workshop, we covered this relatively new SSH key material for the first time and encountered some issues/challenges. Following a discussion on Carpentries Slack it was suggested to open an issue here to report back on this - it would be great to hear others' experiences with this material and whether there's anything we could do differently at future workshops or whether there are possible updates that can be made to the material to help simplify this element of the lesson.

---

Notes on our experiences of setting up SSH keys when teaching the git material

I understand the reasoning for adding this content to the lesson and I certainly agree that it needs to be there but I think our takeaway from this is that it would be good to find a way to cover this material such that it doesn't result in lots of issues that then consume time in the middle of the Git lesson that could detract from the learning of the core git skills.

Here's a summary of the observations from members of the workshop team involved in teaching this lesson at our most recent workshop:

• Use of default key locations (as things are covered in the material) does simplify the process, however, this may cause issues for learners who are not familiar with SSH but already have a key in place with the default filename that is being used for, e.g. connecting to a institutional HPC cluster, making a remote connection to an office desktop, etc. In such cases, if the default key is overwritten, this will break existing configuration. I've detailed our experiences around this point in issue Mention the importance of using the default SSH key location #846 since I thought they were relevant to that existing issue.

• We've previously covered the git session in a half-day slot of a 2-day shell, git, python workshop and found timing to be somewhat limited. With this new material, we found that after using a key with a custom filename (i.e. not accepting the default name), we spent a total of around 45 minutes covering the SSH key section of the material and still had some learners stuck without a working connection. We had already planned to run an optional, informal 2-hour shell/git clinic session the following day and several people attended that with key-related issues, we spent much of the time explaining the reason for using keys, why they are set up the way they are, why you might not want to use the default filename, and generally running people through the key creation process again. Ultimately, we felt we may need somewhere around 4.5-5 hours to cover all that we wanted to cover on git without it being rushed.

• Would an alternative option be to cover creating a personal access token which, as far as I'm aware, can then be used for command line authentication in the same way that a regular account password was previously? While you can constrain the permissions of a PAT, I suppose this may not be classed as good practice but maybe it could be worth highlighting this as a short-term workaround?

[jcohen02]

Just a quick follow-up to note that I've just noticed #824 and I see that this does look at PAT as a possible option. Great to see that there's already discussion going on around this but I note that, if I understand correctly, this is being considered as an additional set of material that would be classed as intermediate level?

[kekoziar]

@jcohen02 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).

I'm glad you found the supplemental SSH episode still in development which includes PATs. Please feel free to contribute. Issue #824 describes how to contribute. I'm closing as duplicate