Add ssh-keygen troubleshooting info for Windows#43714
Add ssh-keygen troubleshooting info for Windows#43714Infinitay wants to merge 7 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.
github-actions
bot
added
the
triage
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. |
...ion/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md
Outdated
Show resolved
Hide resolved
Fixed lint error MD031, blanks-around-fences (Fenced code blocks should be surrounded by blank line)
Sharra-writes
added
content
|
@Infinitay I'm checking to make sure this isn't too niche for us to document, since we can't possibly document every possible case. If I get approval, I'll find an SME to review the content. |
|
That's understandable. I just figured I'd include it since it took me some time to finally find the cause and solution to my problem. I wanted to note more information but I'm not an expert. Otherwise, I would've liked to more generalize the problem by saying something such as,
However, as I said, I am worried this is rather an assumption because I'm not entirely sure if this is true - where the binary has to be the exact same for both generating the key and validating it. |
|
@Infinitay The team has approved this as being a low-risk addition that shouldn't require too much maintenance, since Windows is unlikely to fix the problem it addresses. I need to edit it a bit for style, drop in a link to Git for Windows, and then give it to one of the other writers for a final examination/edit. I'm arguing with Codespaces and some versioning right now, but I'll get to this when I can. |
...ion/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md
Outdated
Show resolved
Hide resolved
...ion/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sharra-writes <sharra-writes@github.com>
There was a problem hiding this comment.
Pull request overview
Adds Windows-specific troubleshooting guidance to help readers avoid conflicts between the Git for Windows OpenSSH tools and Windows’ built-in OpenSSH when working with the SSH agent.
Changes:
- Adds an external link to Git for Windows in the Windows SSH-agent troubleshooting callout.
- Adds additional troubleshooting steps suggesting configuration of
gpg.ssh.programand reinstall guidance to prefer external OpenSSH.
Show a summary per file
| File | Description |
|---|---|
| content/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md | Expands the Windows troubleshooting callout with extra guidance intended to reduce OpenSSH binary/agent conflicts. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 3
| > | ||
| > 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" | ||
| > ``` | ||
| > |
There was a problem hiding this comment.
gpg.ssh.program configures which ssh-keygen Git uses for SSH commit/tag signing (when gpg.format=ssh), not which SSH client Git uses for operations like git push or which agent is used. In this “SSH agent conflicts” troubleshooting section, this command is likely misleading; consider removing it or explicitly scoping it to SSH signing (and explaining when it applies).
| > | |
| > 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" | |
| > ``` | |
| > | |
| > |
There was a problem hiding this comment.
@Infinitay I understand most of these words, but not in context. Is this something that needs to be addressed or is Copilot mistaken?
...ion/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md
Outdated
Show resolved
Hide resolved
...ion/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md
Outdated
Show resolved
Hide resolved
…g-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…g-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
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: