chore: update guide to include path to public key for ssh signing

[mitche50]

The config file for using SSH paths may not be parsed correctly on some systems. Add in a hint in the documentation to give an alternative to use the direct path to your ssh pubkey file instead of the contents of your key.

Why:

Closes [issue link]

What's being changed (if available, include any code snippets, screenshots, or gifs):

Check off the following:

• [ ] I have reviewed my changes in staging (look for the "Automatically generated comment" and click the links in the "Preview" column to view your latest changes).
• [x ] For content changes, I have completed the self-review checklist.

Writer impact (This section is for GitHub staff members only):

• [ ] This pull request impacts the contribution experience
  • [ ] I have added the 'writer impact' label
  • [ ] I have added a description and/or a video demo of the changes below (e.g. a "before and after video")

[welcome[bot]]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@mitche50 Thanks so much for opening a PR! I'll get this triaged for review :zap:

[github-actions[bot]]

Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert :eyes:

[vtbassmatt]

:wave: hi from the product manager for Git Systems. Thanks for opening this PR!

I'm curious on what systems you've (or the internet at large has) seen a problem with using the literal key in this fashion. I couldn't find much with some searching, including on the Git mailing list, but I'm open to the idea that my search syntax was poor 😅 Could you send any pointers you have?

After doing some deep-diving on this topic, I have two alternate proposals for the docs team:

1. It looks like we could always suggest pointing to a file rather than a literal key, with no loss of functionality for our customers. Depending on what @mitche50 comes back with, we might want to change to that format and drop the literal syntax from our docs entirely.
2. Alternatively, we should emphasize the fact that you have to prefix your literal key with key::. That's not completely obvious as-written, and if you "merely" paste your key in without the prefix, you're relying on backcompat behavior in Git which may not be forwards-compatible with future key types. Something like this should work, assuming the user correctly did the pbcopy step:

$ git config --global user.signingkey "key::$(pbpaste)"

(NB I didn't actually test that syntax, I wrote it from memory.)

[mitche50]

The documentation (even with the key:: prefix) did not work on Ubuntu 20.04.02 running on WSL2. This may be relegated to just whatever internally is happening on the VM that the windows linux kernel is using, but WSL2 is prevalent enough to at least address it.

IIRC (this issue was created a while ago) I had colleagues who had done this successfully with the literal key on macbooks, unsure if I had anyone who was running bare metal linux distribution comment.

[vtbassmatt]

Thanks @mitche50, I appreciate the additional detail. What do you think about basically replacing our guidance to use a bare key with advice to use the file path (rather than having one, then the other as fallback)? From my read of the Git mailing list, that seems to be the preferred approach when the feature was designed.

[mitche50]

I think this works as well, the file should be compatible with all systems 👍

[timja]

I've verified on MacOS BigSur

with:

❯ ssh -V
OpenSSH_9.0p1, OpenSSL 1.1.1q  5 Jul 2022
❯ git --version
git version 2.37.3

Using file path only means you don't need to pass the key inline or have an ssh agent running

diff --git a/config/git/config b/config/git/config
index 7aedf53..0df39fb 100755
--- a/config/git/config
+++ b/config/git/config
@@ -3,7 +3,7 @@
 # Please adapt and uncomment the following lines:
        name = Tim Jacomb
        useConfigOnly = true
-       signingkey = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDnTfTt8lqJdcucKu538C6EvPNruiO9r67Jvfrbokear (omitted)\n
+       signingkey = ~/.ssh/id_ed25519.pub

[cmwilson21]

Hey @mitche50, are you up for making the changes to this PR that Matt suggested in the previous comment? No worries if not ✨

[mattpollard]

👋🏻 @mitche50, I'm planning on working on this early next week, but if you've got a chance and the interest before then, feel free to incorporate the changes that @vtbassmatt suggested ☺️

[japui-coder]

Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).

[mattpollard]

Thanks, @mitche50 🙇🏻 We'll merge this at the end of the week after our freeze for GitHub Universe 2022 is over.

[github-actions[bot]]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues :zap:

[timja]

This is a nice improvement but it needs review against where the include is used, i.e. some docs don't make sense right now.

https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key#telling-git-about-your-ssh-key

section 3, asks you to copy a key that isn't needed

[mattpollard]

@timja 👋🏻 Sorry, I lost track of this. The doc you links to looks alright to me, and doesn't seem to mention copying a key. Can you clarify?

[timja]

Seems to have been fixed, can't remember exactly what was there I should have taken a screenshot.

[Gojekgobiz]

Seems to have been fixed, can't remember exactly what was there I should have taken a screenshot.