When working with Mercurial repositories over SSH on Windows, many developers generate keys using PuTTYgen (resulting in .ppk files) but struggle to integrate them with TortoiseHg's native SSH implementation. The standard Mercurial command-line and TortoiseHg GUI don't directly expose PPK key configuration options.

Before proceeding, ensure you have:

1. PuTTY installed (includes Pageant and Plink)
2. Generated PPK key pair via PuTTYgen
3. Public key deployed to the remote server

Method 1: Using Pageant (Recommended)

The most reliable approach uses PuTTY's authentication agent:

1. Launch Pageant from PuTTY installation directory
2. Right-click its system tray icon → "Add Key"
3. Select your .ppk file and enter passphrase
4. Configure TortoiseHg to use Plink:

Edit Mercurial.ini (or create if missing):

[ui]
ssh = "C:\Program Files\PuTTY\plink.exe" -ssh -i "C:\path\to\your\private.ppk" -batch

Method 2: Direct Plink Integration

For environments where Pageant isn't feasible:

[ui]
ssh = "C:\path\to\plink.exe" -ssh -i "C:\keys\your_key.ppk" -batch

Test your configuration with:

hg clone ssh://user@hg.example.com/repo

For debugging, add -v flag:

[ui]
ssh = "C:\path\to\plink.exe" -ssh -v -i "C:\keys\debug_key.ppk"

Authentication Failures

If you receive "Access denied" errors:

1. Verify Pageant is running with correct key loaded
2. Check remote ~/.ssh/authorized_keys file permissions (should be 600)
3. Confirm PuTTY and TortoiseHg bitness match (both 32-bit or 64-bit)

Connection Timeouts

For network-related issues:

[ui]
ssh = plink.exe -ssh -P 2222 -i key.ppk  # Non-standard port example

For teams managing multiple keys:

[auth]
example.prefix = hg.example.com
example.username = dev_user
example.ssh = "C:\tools\plink.exe" -ssh -i C:\keys\project_specific.ppk

Remember to restart TortoiseHg after configuration changes. For production environments, consider using SSH configuration files for more complex setups.

---

When working with Mercurial (Hg) repositories via SSH on Windows, developers often generate key pairs using PuTTYgen (creating .ppk files) but struggle to integrate them with TortoiseHg or command-line Mercurial. The fundamental issue lies in the mismatch between PuTTY's proprietary key format and OpenSSH's expected format.

Before proceeding, ensure you have:

1. PuTTYgen-installed .ppk private key (e.g., hg_key.ppk)
2. Pageant running (PuTTY authentication agent)
3. TortoiseHg 6.0+ or Mercurial 5.0+
4. PuTTY installed (typically comes with TortoiseHg)

The most reliable approach leverages PuTTY's authentication agent:

# Step-by-step implementation:
1. Launch Pageant from PuTTY installation folder
2. Right-click Pageant in system tray → 'Add Key'
3. Select your .ppk file and enter passphrase if applicable
4. Configure Mercurial.ini to use plink:

[ui]
ssh = "C:/Program Files/TortoiseHg/lib/plink.exe" -ssh -2 -batch -C -i "C:/path/to/your_key.ppk"

Real-world example: When cloning from Bitbucket:

hg clone ssh://hg@bitbucket.org/username/reponame

For environments where Pageant isn't available:

1. Open PuTTYgen → Load existing .ppk
2. Navigate to Conversions → Export OpenSSH key
3. Save as id_rsa (no extension)
4. Place in C:/Users/username/.ssh/
5. Update Mercurial.ini:

[ui]
ssh = "C:/Program Files/Git/usr/bin/ssh.exe" -i "C:/Users/username/.ssh/id_rsa"

Error: "Permission denied (publickey)"
Verify:

- Pageant is running with loaded key
- Correct key is associated with remote account
- No whitespace in .ppk file path

Error: "Server refused our key"
Solution:

1. Check remote server's authorized_keys file format
2. Ensure public key is properly installed:

# Example for Bitbucket:
ssh-rsa AAAAB3NzaC1yc2E... comment@yourmachine

For teams using multiple keys:

[auth]
example.prefix = ssh://hg@example.com
example.username = hg
example.privatekey = C:/keys/example_key.ppk
example.type = ssh

This enables per-repository authentication without global configuration.