Skip to content

Add ssh-keygen troubleshooting info for Windows#43714

Open
Infinitay wants to merge 2 commits intogithub:mainfrom
Infinitay:patch-1
Open

Add ssh-keygen troubleshooting info for Windows#43714
Infinitay wants to merge 2 commits intogithub:mainfrom
Infinitay:patch-1

Conversation

@Infinitay
Copy link
Copy Markdown

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:

  • A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require an SME review from GitHub staff.
  • The changes in this PR meet the docs fundamentals that are required for all content.
  • All CI checks are passing and the changes look good in the review environment.

Added troubleshooting instructions to help avoid binary conflicts with the ssh-keygen binary between Git for Windows and Window's OpenSSH.
Copilot AI review requested due to automatic review settings April 7, 2026 20:42
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Apr 7, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

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 links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source Review Production What Changed
authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md fpt
ghec
ghes@ 3.20 3.19 3.18 3.17 3.16 3.15 3.14
fpt
ghec
ghes@ 3.20 3.19 3.18 3.17 3.16 3.15 3.14

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.exe for SSH operations.
  • Adds additional guidance suggesting gpg.ssh.program configuration and a Git for Windows reinstall option to prefer external OpenSSH.

Comment on lines +179 to +184
>
> 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.
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
>
> 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.

Copilot uses AI. Check for mistakes.
> ```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.
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Suggested change
> 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.

Copilot uses AI. Check for mistakes.
Fixed lint error MD031, blanks-around-fences (Fenced code blocks should be surrounded by blank line)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage Do not begin working on this issue until triaged by the team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants