Gitosis for Mercurial

As far as DVCSs go I’ve been a git user. That’s mostly because it was the first one I tried and it worked. I’ve been comfy and have enjoyed the world of git and GitHub, but a number of troublemakers have been trying to convince me to give Mercurial a shot. After some nudging I obliged.

After a day or two of toy and experimental projects I started missing one of my primary git utilities–Gitosis. Gitosis is a package that lets you and all your collaborators interact with your git repositories using a single user account over SSH. Gitosis manages user authentication and permissioning using a system of shared keys without ever exposing actual shell functionality.

It took me a little while to find mercurial-server by LShift, which seems to be Mercurial’s equivalent to Gitosis. So, here is how I got Gitosis-style shared key repository management to work with Mercurial.

Installing Mercurial-Server on Ubuntu 9.10 (Karmic)

Luckily, Paul Crowley of LShift, the author of mercurial-server, has volunteered to manage a Debian package for Mercurial-Server, which makes our lives easier. Thanks!

Install the Mercurial-Server Package

Add the following line to your /etc/apt/sources.list file replacing the url with a mirror that’s appropriate for your location:

deb lucid main universe


$ sudo apt-get update
$ sudo apt-get install mercurial mercurial-server

OR, if you want to install the package manually outside of synaptics or apt you can download the .deb from and then:

$ sudo dpkg -i mercurial-server_1.0.1-1_all.deb

Mercurial-Server should now be installed. Additionally, a new user hg has been created and will be used to manage all your interactions with your mercurial repositories.

Setting Up Mercurial-Server Administrator (root)

You now need to grant yourself administrator rights. All permissioning is done with keys, so you’ll need to copy your public key to mercurial-server’s admin keyring:

$ sudo cp /etc/mercurial-server/keys/root/YOURUSERNAME

$ sudo -u hg /usr/share/mercurial-server/refresh-auth

The second command refreshes mercurial-server’s authentication system–authorizing your account as an administrator. You’re good to go!

Managing Mercurial-Server

The hgadmin Repository

Just like gitosis’ gitosis-admin repository, mercurial-server’s functionality can be managed via hgadmin. Go ahead and clone the repo:

$ hg clone ssh://hg@MyMercurialServer/hgadmin

Adding New Users

With your hgadmin repository cloned you can now grant access to new users via their public keys

$ cd hgadmin
$ mkdir -p keys/users/
$ cp ~/ keys/users/kurt
$ hg add
adding keys/users/kurt
$ hg commit -m "Added Kurt's public key"
$ hg push

You can also allow and organize multiple keys per user. In that scenario you create a directory of keys for each user:

$ cd hgadmin
$ mkdir -p keys/users/kurt
$ cp ~/ keys/users/kurt/home
$ cp ~/ keys/users/kurt/work
$ hg add
adding keys/users/kurt/home
adding keys/users/kurt/work
$ hg commit -m "Added keys for Kurt's home and work computers"
$ hg push

Creating New Repositories

As administrator, if you want to create a new repository you simple clone a mercurial project to a path on your mercurial-server. For example:

$ cd my_hg_proj
$ hg clone . ssh://hg@MyMercurialServer/my_hg_project

Now you and your collaborators can clone, push, and pull from the server’s repository just as we did with hgadmin. For example:

$ hg clone ssh://hg@MyMercurialServer/my_hg_project

Managing Repository Permissions

Now that you’ve created your repositories and added users you will want to manage permissions. Repository permissions can be managed through an hgadmin file called access.conf. I recommend reading the mercurial-server documentation for more information on managing security.

So far I’ve found mercurial-server to be a great way to collaborate with others on private repositories outside of Bitbucket. My hat off to Paul Crowley and LShift.

Leave a Reply

Your email address will not be published.