remote hg with http

Following is a solution for a Mercurial repository that can be browsed and updated over HTTP.

No small animals were injured or killed in the producing of this documentation.

This was tested on Red Hat Enterprise (RHEL) Linux 6.

Variations on aspects of this solution, for example publishing over HTTPS rather than HTTP, or dispensing with authentication, are noted below.

In this example the repository will be located on “”, and the workgroup being served will be “ourteam”. The only prerequisites are that the server have the Apache HTTP Server installed along with a recent copy of Mercurial (for RHEL systems the version 2.2.2 rpm from rpmforge will do), and if LDAP authentication is desired, the mod_authz_ldap module.

We’ll call the repo being published “bigcode”.

The official documentation for what following is in the article, Publishing Repositories, on the Mercurial wiki.

Repository Creation

The first step is to create a “shared” repository that can be accessed by many users.

1. Set up a system user and group on the “shared” host.

groupadd -g 2027 hg
useradd -g hg -u 2027 -c "Mercurial User" hg
passwd hg __________

By the end of this procedure the repository files will all be owned by the Apache web server user, but setting up a special user and group to perform the preliminary work is useful (and preferable to doing everything as root!).

2. Create an .hgrc in this user’s home directory.

cd /home/hg
printf "[ui]\nusername=Mercurial \n" >.hgrc

3. Create the shared file system and make that user owner:

mkdir /data/hg
chown hg:hg /data/hg
chmod g+w /data/hg

4. Create and initialize a repository under the shared file system.

mkdir bigcode
cd bigcode
hg init

Publish the Repository

1. Copy hgweb.cgi from the Mercurial distribution to the shared directory.

cp /usr/share/doc/mercurial-2.2.2/hgweb.cgi /data/hg

2. Create an hgweb.config file for hgweb.cgi alongside it.

# /data/hg/hgweb.config
/ = /data/hg/*

descend = True

3. Modify hgweb.cgi so that it points to this new config file.

# Path to repo or hgweb config to serve (see 'hg help hgweb')
config = "/data/hg/hgweb.config"

4. Create an .htaccess file in the directory to secure the site using Apache’s mod_authnz_ldap.

# /data/hg/.htaccess
AuthType Basic
AuthName "ourteam"
AuthBasicAuthoritative off
AuthBasicProvider ldap
AuthzLDAPAuthoritative off
AuthLDAPURL ldap://,dc=com?uid?sub?(uid=*)
AuthLDAPBindDN "uid=appuser,ou=people,dc=example,dc=com"
AuthLDAPBindPassword xxxxx
require ldap-group cn=ourteam,ou=groups,dc=example,dc=com

If you don’t think you need authentication, then don’t create an .htaccess file. You could also substitute a different “back end”, like an htpassword file or a MySQL database. Check the documentation for Apache basic authentication for more.

5. Modify /etc/httpd/conf/httpd.conf to configure for publishing the site by adding the following:

ScriptAlias /hgweb "/data/hg/hgweb.cgi"

       Options All
       AllowOverride All
       Order allow,deny
       Allow from all

Note: If you’re running Apache 2.4.x, you’ll need to replace the “Order” and “Allow” directives above with a “Require all granted”.

If you want to require HTTPS be sure this configuration appears in your SSL virtual host block and not the non-SSL ones.

6. Create an hgrc file under each shared repository’s .hg directory and configure so that updates can be done by “anyone” over HTTP.

# /data/hg/bigcode/.hg/hgrc

contact = Duke Nukem 
description = Our Team Files
allow_push = *
push_ssl = false

If the web site will be published over HTTPS (always recommended, rarely heeded) then set “push_ssl” to “true”.

7. Make the HTTP server user owner of the shared directory so that it can be written to over HTTP.

chown -R apache:hg /data/hg

8. HUP the web server (as root).

service httpd reload

User Configuration

1. Create a $HOME/.hgrc for each remote user.

username=Phil Lembo 

2. Create a local sandbox and clone the “shared” repositories to it.

cd ~
mkdir hg
cd hg

Provide the LDAP uid (GlobalID) and password of the user on request.

If the site will be HTTPS, make sure the url above reflects that.

3. Verify that the local copy of the repository has an hgrc file that points back to the shared repository.

cat ~/hg/bigcode/.hg/hgrc

default =

Again, if the site is HTTPS, conform the above url to same.


Set up a simple shell script to copy the repository to a safe place every night, “just in case”, keeping in mind that because it is distributed there will be many “backup copies” across the team.