mercurial server integration cube

Simple setup

This is the simplest setup, with mercurial-server and the Cubicweb application running on the same server.

  • get and install mercurial-server:

    apt-get install mercurial-server

    Or from sources:

    hg clone
    # remove installdoc from installfiles target of Makefile, then run (as root):
    # (files go to /etc/mercurial-server and /var/lib/mercurial-server)
    # (command line for debian-like systems, for redhat like, see official doc).
    make setup-adduser

    Official documentation can be found at and in the README file in the mercurial-server sources.

  • login as the user running the Cubicweb app with the mercurial_server cube; make sure this user has a rsa ssh key in ~/.ssh/ and run:

    sudo mkdir -p /etc/mercurial-server/keys/root/$USER
    sudo cp ~/.ssh/ /etc/mercurial-server/keys/root/$USER
    sudo -u hg /usr/local/share/mercurial-server/refresh-auth

Basic usage

The user running the Cubicweb instance must have the SSH key registered in mercurial-server configuration (see above) unlocked and available through an SSH agent.

Run and connect to the web interface, and add a new mercurial-server repository.

You can clone it immediately, start coding and push it back to the server.

Your changes are integrated into the CW application on a regular basis through a vcsfile cube recurring task (see [VCSFILE] check-revision-interval setting in your all-in-one.conf).

Using the Mercurial Server cube

The mercurial-server cube provides a way to participate in the edition of a mercurial-server configuration.

It provides:

  • a configuration object (MercurialServerConfig entity type) that maps a mercurial-server configuration,
  • repositories objects (Repository entity type), one representing the hgadmin repository (through the hgadmin_repository relation type) and the other the actual end-user repositories (through the hosted_by relation type),
  • end-user public keys (SshPubKey entity type, used to authenticate clone, pull and push operations with respect to the repositories they own),
  • permission objects (MercurialServerPermission entity type) that map repositories to end-user public keys, along with a specific access level (deny, read, write)


CubicWeb instance side

The MercurialServerConfig entity must be set up with the following attributes:

  • a symbolic name (to show them in the web interface in a user friendly way)
  • a base_url that will be common to all the managed repositories (including the hgadmin repository), e.g. ssh://
  • the name of the hgadmin repository (hgadmin is a good default and should probably not be edited)
  • the name of the access configuration filename (the default access.conf can be replaced by a more specific access_<appid>.conf name that will allow convenient rules segregation, e.g. between local hand-maintained sysadmin rules and this MercurialServerConfig instance)
  • the keys subdir which can be set to <appid>keys for better data segregation (same reason as above)
Mercurial-Server side

If a non default access conf filename is used, the mercurial-server side must be informed to use it, by editing the /var/lib/mercurial-server/.mercurial-server file:

  • append ~/repos/hgadmin/<access_conf_file_name> to the access entry under the [path] section
  • nothing has to be done with respect to the custom keys subdir fragment.


A complete mercurial-server configuration must be set up first.

Perform the initialization steps as above:

  • the MercurialServerConfig entity can then be created.
  • the mercurial-server side must be adjusted.

From now, MercurialServerPermission creation, edition or deletion will trigger automatic update of the controlled access configuration file.

Also, the end-user can create repository objects hosted by the mercurial server config object: actual mercurial repositories will be created remotely and their owner will be able to clone them, using the provided uri.

There exists a regenerate action on the MercurialServerConfig entities main view that will force a full regeneration of the access file and of the keys if clicked upon. This can be useful at server startup, after a database restore, or if a sysadmin murked away the original hgadmin repository.

As a side effect, user keys (reachable from such permission objects) may be added or deleted to the keys/<keys subdir> segment in the hgadmin repository, and the <access conf file> will be entirely regenerated.

Be aware that the mercurial-server cube will NEVER try to synchronize itself back from the current state of the hgadmin repository. It is a one-way trip.

On deletion of a MercurialServer entity, the access files and relevant user keys will be destroyed in the hgadmin repository.

source repositorymercurial-server repository
test environmentmercurial-server env
owned byddouard
may be discussed onCubicWeb
use licenseLGPL