Announcements‎ > ‎

How to Collaborate using Mercurial with hg-ssh

posted Jan 28, 2011, 10:43 AM by Ken Jones


This document assumes you have installed both the ssh client and sshd, Mercurial and that you have a basic knowledge of UNIX type commands.

The instructions here will help you to use Mercurial with multiple committers, those who will be collaborating on your project. It is a assumed that a repository manager has created one, or more, Mercurial repositories to be used by the collaborators. In the tutorial the collaborators will create SSH public keys to give to the repository manager.  The repository manager will place in the SSH authorized keys file, on the host machine with the repositories, in such a way as to give easy and protected access to the repositories.

Collaborators Instructions

Create new SSH keys on remote machine

Any collaborator you would like to have access to your Mercurial repository should follow these steps to send you a new public SSH key on their host. The name of the key should be unique, it could be the name of your project for example. In this case it will be called “project_hg_id_dsa”.

Log into your development desktop and use this command:

$ ssh-keygen -t dsa -f ~/.ssh/project_hg_id_dsa

At this point you should enter a good passphrase. Do not leave the passphrase blank.

This will produce two keys, project_hg_id_dsa and Give a copy of to the repository manager, perhaps by email.

Repository Manager

Add all public keys to authorized_keys

Append all the public keys to your SSH authorized keys file on the host that has your Mercurial repositories. The authorized keys file may vary slightly depending on the version of SSH in use, or in the way it was configured. ~/.ssh/authorized_keys or ~/.ssh/authorized_keys2 are some common authorized keys file names. Consult your system administrator if you have problems figuring out what file to use. If the file doesn’t exist, created it, and give it permissions so the user only has access:

$ chmod 700 ~/.ssh/authorized_keys2

It’s best to restrict what commands your collaborator can access with SSH, so, the key should start with a line that looks like this:

command=”hg-ssh <repo> <repo>”,no-port-forwarding,no-X11-forwarding,no-agent-forwarding

Note: There are no spaces allowed in a key line in the authorized key file, unless they are in quotes “ “. So, no spaces after commas, or anywhere.

So, if you had 3  repos in your home directory, you might want to give access to all three to someone, the whole entry in your authorized_keys file might look like this:

command=”hg-ssh ~/MyProject1 ~/MyProject2 ~/Myproject3″,no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-dss AAAAB3NzaC1kc3BAKqYY… <BIG BLOCK OF CODE HERE> …HzBKXgq3KAjfxBmgxlozLIzg==

Add one of these lines for every collaborator’s public key.


Now your collaborators should have access via Mercurial and SSH.  In this example we will use ssh-agent to cache our key’s password. Also, notice that one needs to use the repo managers account name in the Mercurial SSH URL, we will call that account “repo_manager” in this example.

$ ssh-agent $SHELL

$ ssh-add ~/.ssh/project_hg_id_dsa

Enter passphrase for /home/youraccount/.ssh/project_hg_id_dsa:

<User enters password now>

Identity added: /home/youraccount/.ssh/project_hg_id_dsa (/home/youraccount/.ssh/project_hg_id_dsa)

$ hg clone ssh://

One can pull and push as well, in order to push or pull changes to your repo. Don’t forget one has to use “hg update” to see any file changes on the host that holds the repo (the logs will show the changes, and clones and pulls will have the changes).

Further Reading, Hints, and Tips



Learning Mercurial in Workflows