Skip to content

Review on SSH chapter #61

Closed
Closed

Description

@SvonGrebmer

Hello @NeuroShepherd ! Here my thoughts/suggestions:

(working my way top to bottom)

  • When working with a GitHub repository, you’ll often need to identify yourself to GitHub using your username and password. There are several ways to secure this connection further. Establishing a secure connection is mandatory since August 2021. --> change to "When working with a GitHub repository, you’ll often need to identify yourself to GitHub using your username and password. However, since August 2021, higher security standards for this connection have become mandatory. Therefore, we will use SSH ...
  • The procedure below only needs to be executed
  • Under generating an SSH key pair: In the command line .. add "In the command line of your terminal, type the following ....
  • Under generating an SSH key pair: -C flag and -f is this critical information for non-developers?
  • Under generating an SSH key pair: This is the prompt that will appear: -> Here I would also rearrange and say something like, next, you will see this prompt (image of prompt), then mention to press enter and that the default file loc is accepted.
  • Under generating an SSH key pair: Passphrase: reminded me I need to remove it from my own keys
  • Under creating the SSH config file: This file simply tells the SSH software --> This file tells the SSH software
  • Under creating the SSH config file: this is new ..? Have not done this in almost two years, but looks unfamiliar!
  • Under creating the SSH config file: Formatted the text in the config file should look like this -> perhaps mention that it can be found in the .ssh folder? And when you then say you can simply paste the above lines into the config file, I would be confused as a reader if both the Host github.com and/or also what follows # Add the following lines - perhaps put the "Formatted, the text .." bit after you mention to paste it into the config file?
  • Under Adding a new SSH key to your GitHub account: Be careful etc: at this point, I think I would not know where I could copy my private key? Did I paste it to clipboard somewhere before? What am I missing? Putting below the cat command prompt
  • Under adding your key to the ssh-agent: It is correct to say that only GNU/Linux do notwarrant this step? Did you want to specify that if you are using Windows/Mac (probably most users?) would need to follow this step? It is a little unclear at this point for whom this step is
  • Under adding your key to the ssh-agent: Small thing about Capitals in the section title: you sometimes use them, sometimes not, just for consistency
  • Under Testing Your Connection to GitHub: Great! I also remember the original instructions here being longer?
  • Under Testing Your Connection to GitHub: Going forward, you can use the SSH clone URL etc: perhaps a step too far? I imagine a novice just having been successful in setting this up, a clone URL might be too much at this point? Clarify or mention what will be covered in the second tutorial without using this technical term

Activity

  1. MalikaIhle commented on Aug 31, 2026

    @MalikaIhle
    Member

    Hi both, I was reviewing my content for the summer school and noticed the SSH page significantly changed and then found this issue.

    • "It’s fine if .ssh is empty or doesn’t exist yet;" --> I don't think they will know how this looks like, or, if they have one if they will know how it looks like.
    • maybe having the choice of naming the keys might be overwhelming - there is the code (which they will copy brain dead) and then explanation then the option not to do that ect. Maybe standardize so all do the same so we know what to look for when debugging?
    • Creating the SSH Config File --> I ahve never done that - what is this? is this needed for this workshop?
    • SSH agent: when this seciotn was added I thought this was so that my passphrase would stop being asked upon pushin (which kept being asked anyway) - now we say not to add a passphrase anyway. What is the prupose of this section? do we need it for this workshop? I'm trying to see whether we can keep it to the minimum as this page is the most overwhelming and least on topic for the git workshop.
  2. NeuroShepherd commented on Aug 31, 2026

    @NeuroShepherd
    Member

    I made two substantive changes to the SSH chapter last week:

    1. I removed the recommendation to add a password to the SSH key as this was a recurring source of problems (i.e. people forgetting passwords, people not understanding that the terminal does not show password input text even though we included a note about this, etc.) In an ideal world, I would recommend people use a passphrase and store it, but this is leading to substantial friction. I'm open to rolling back this change, however.
    2. I changed the SSH generation procedure to save the SSH key into a specific file rather than going into the default files. Why? Because the default behavior of running ssh-keygen is to overwrite the default file so if any of our summer school participants use ssh-keygen in the future, they will inadvertently overwrite their GitHub SSH key (and likely not understand why they can no longer connect.) This will likely occur for many who attempt to connect to LRZ GitLab, for example.

    The rest of the tutorial I left alone.

  3. MalikaIhle commented on Aug 31, 2026

    @MalikaIhle
    Member

    I removed the recommendation to add a password to the SSH key --> fine by me.
    I changed the SSH generation procedure to save the SSH key into a specific file rather than going into the default files. --> sure but maybe let's not make it optional in the main text (maybe only in the footnote) to not be overwhelming.

  4. linked a pull request that will close this issueIncorporate feedback on SSH updates #62on Aug 31, 2026
  5. MalikaIhle commented on Sep 1, 2026

    @MalikaIhle
    Member

    ok I reviewed all against our comment @SvonGrebmer - no need for you to review again - it's all addressed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions