Add ssh-keygen troubleshooting info for Windows#43714
Add ssh-keygen troubleshooting info for Windows#43714Infinitay wants to merge 2 commits intogithub:mainfrom
Conversation
Added troubleshooting instructions to help avoid binary conflicts with the ssh-keygen binary between Git for Windows and Window's OpenSSH.
How to review these changes 👓Thank you for your contribution. To review these changes, choose one of the following options: A Hubber will need to deploy your changes internally to review. Table of review linksNote: Please update the URL for your staging server or codespace. The table shows the files in the
Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server 🤖 This comment is automatically generated. |
There was a problem hiding this comment.
Pull request overview
Adds Windows-focused troubleshooting guidance to help readers avoid passphrase prompts caused by Git using a different OpenSSH client than the Windows ssh-agent service.
Changes:
- Adds a Git configuration example to force Git to use the Windows system
ssh.exefor SSH operations. - Adds additional guidance suggesting
gpg.ssh.programconfiguration and a Git for Windows reinstall option to prefer external OpenSSH.
| > | ||
| > Furthermore, you may need to specify which `ssh-keygen` binary Git should use to avoid conflicts with the binary bundled with Git for Windows. To define which binary is used, run the following command: | ||
| > ```powershell | ||
| > git config --global gpg.ssh.program "C:/Windows/System32/OpenSSH/ssh-keygen.exe" | ||
| > ``` | ||
| > Alternatively, you can re-install Git for Windows and select the "Use external OpenSSH" option during the installation process. |
There was a problem hiding this comment.
git config --global gpg.ssh.program ... only affects Git’s SSH-based signing/verification (when gpg.format=ssh), not which ssh-keygen is used for SSH authentication or for generating keys. In this “SSH agent conflicts” troubleshooting section, this reads like it will resolve git push/agent passphrase prompts, which it won’t. Consider either removing this paragraph, or explicitly scoping it to SSH commit/tag signing (and linking to the SSH signing docs), and keeping the agent-conflict guidance focused on core.sshCommand/which ssh.exe Git uses.
| > | |
| > Furthermore, you may need to specify which `ssh-keygen` binary Git should use to avoid conflicts with the binary bundled with Git for Windows. To define which binary is used, run the following command: | |
| > ```powershell | |
| > git config --global gpg.ssh.program "C:/Windows/System32/OpenSSH/ssh-keygen.exe" | |
| > ``` | |
| > Alternatively, you can re-install Git for Windows and select the "Use external OpenSSH" option during the installation process. | |
| > | |
| > Alternatively, you can reinstall Git for Windows and select the "Use external OpenSSH" option during installation. |
| > ```powershell | ||
| > git config --global gpg.ssh.program "C:/Windows/System32/OpenSSH/ssh-keygen.exe" | ||
| > ``` | ||
| > Alternatively, you can re-install Git for Windows and select the "Use external OpenSSH" option during the installation process. |
There was a problem hiding this comment.
The installer option name is a UI element; per the docs style guide, it should be formatted in bold rather than in quotation marks (for example, Use external OpenSSH).
| > Alternatively, you can re-install Git for Windows and select the "Use external OpenSSH" option during the installation process. | |
| > Alternatively, you can re-install Git for Windows and select the **Use external OpenSSH** option during the installation process. |
Fixed lint error MD031, blanks-around-fences (Fenced code blocks should be surrounded by blank line)
Added troubleshooting instructions to help avoid binary conflicts with the ssh-keygen binary between Git for Windows and Window's OpenSSH.
Why:
I recently faced lots of trouble trying to figure out why I was constantly being asked to provide the passphrase associated with the ssh/signing key. I finally resolved the issue by explicitly defining which gpg ssh program to use via
git config --global gpg.ssh.program "C:/Windows/System32/OpenSSH/ssh-keygen.exe". I presume this was because when I (re)installed Git at some point, I didn't select to use an external OpenSSH.What's being changed (if available, include any code snippets, screenshots, or gifs):
I added additional troubleshooting steps for users who are also using Git on Windows and facing troubles with the SSH Agent being used.
Check off the following: