Getting TortoiseHg on Windows to work with SourceHut's SSH authentication

You can skip to the header below for the actual guide. Or stay here for a rambling preamble.

I'm a skilled programmer, but I'm not a technical person. I'm not good with computers. Or at least I highly prefer if things just work, and I don't have to fiddle with settings and configurations.

This is one reason I strongly prefer Mercurial for source control over Git. It has a higher degree of just working. (I don't want to get into an argument over this. You can question my assertion, but my preference is my preference in any case.)

Unfortunately Mercurial has become a niche choice as Git has achieved overwhelming popularity, largely due to GitHub. I wouldn't really have cared about that, except it made BitBucket close down their support for Mercurial some time ago. And BitBucket was a hosting solution for Mercurial that was affordable and also just worked.

I and many other Mercurial lovers have then had to find alternative hosting. And I ended up with  choosing SourceHut. SourceHut is the opposite of "it just works". It's made for people who identify with hacking and tinkering and knowing all the technical stuff. Why did I choose it then? The "just works" alternatives had pricing that just did not work for a game development use case.

Now, SourceHut has been a pain to use in many ways for a non-technical person like me, but I've had the most pain at all trying to get SSH authentication to work. Unlike BitBucket, SourceHut does not allow HTTPS authentication, so you have to use SSH, and nobody ever sat down and made SSH easy to use on Windows.

Getting SSH to work involved juggling things like multiple types of SSH keys and formats all placed in a hidden folder, many different helper tools, and reading dozens of half-baked how-to guides that all contradict each other, often assume prior knowledge, and that are all for slightly different use cases which means they didn't quite work for me.

I got it all to work around a year ago, but I recently wiped my hard drive and needed to do it all over. I couldn't remember anything, so had to figure it all out all over again. So now I'm writing my own half-baked guide, mostly for my future self in case I need it again, but others might stumble over it and maybe find it useful too I guess.

When you read this guide, you might think it doesn't sound that complicated after all. But remember the guide omits all the things I read I should do and which I thus attempted, but it didn't work, and eventually turned out not to be needed anyway. Like running the main PuTTy application, or running tortoiseplink, or editing your mercurial.ini file. Anyway, on to the guide.

Getting TortoiseHg on Windows to work with SourceHut's SSH authentication

Use the instructions here to generate an SSH key and add it to sourcehut:
https://man.sr.ht/tutorials/set-up-account-and-hg.md

Ignore the rest, from "Creating a Mercurial repository" and forward. I assume you already have one, and in this guide we don't want to push with command line since we'll be using TortoiseHg.

Now you should have a id_rsa private key and id_rsa.pub public key inside a folder called .ssh (inside your user folder), which is hidden by default. You can change Windows settings to show hidden files and folders if you want to be able to have a bit better overview.

Download PuTTY. Inside the PuTTY installation folder you'll also find PuTTyGen. Use PuTTyGen to create a id_rsa.ppk key from the id_rsa key using the instructions here:
https://devops.ionos.com/tutorials/use-ssh-keys-with-putty-on-windows/#use-existing-public-and-private-keys
Note: In the open dialog, you need to change the dialog to display "all files" in order to see the id_rsa key. The guide above doesn't mention that. PuTTY can still import it even though it doesn't even display it by default. Save the file as id_rsa.ppk inside the same .ssh folder the other keys are in. Ignore the rest of this guide. You don't need to run the main Putty application itself.

Download TortoiseHg if you haven't already. In the TortoiseHg installation folder, you'll find a helper tool called Pageant. As explained in the tips and tricks section of this guide, we'll want Pageant to automatically load your key when it starts. I'll summarize here:

Make a shortcut to Pageant if you don't have one already. Right click the shortcut and click "Properties". In the Target field in the properties window, you need to keep what's already there but also add a space and then a path (in quotation marks) to your id_rsa.pkk file at the end so it's automatically loaded when Pageant starts.

Now, before you start up TortoiseHg you always need to run Pageant first, using the shortcut you made. Then you should be able to use TortoiseHg to pull and push with SSH authentication.

However, optionally, you can automate this. You can make Windows run your Pageant shortcut on startup by moving the shortcut to the Windows startup folder: Open the “Run” dialog box by pressing the Windows key + R. Type “shell:startup” (without the quotes) in the “Open” edit box and click “OK.”. Copy the shortcut into this folder.

Then you can always use Tortoise without having manually run Pageant first.

That's it! If you have any issues or questions, don't hesitate to - um, to google your issues and try to figure it out. I really can't help you; I don't know what I'm doing. I only barely got this to work myself, and don't really know why, or how it all works. Sorry!