Gitosis for Mercurial

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:

”‘shscript deb lucid main universe “’


“shscript $ 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:

”‘shscript $ 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:

”‘shscript $ 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:

”‘shscript $ 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

”‘shscript $ 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:

”‘shscript $ 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:

”‘shscript $ 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:

”‘shscript $ 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.