4.7.4.1 Mercurial Hook

Since Mercurial is written in python, the hook script can invoke Buildbot's sendchange function directly, rather than having to spawn an external process. This function delivers the same sort of changes as buildbot sendchange and the various hook scripts in contrib/, so you'll need to add a pb.PBChangeSource to your buildmaster to receive these changes.

To set this up, first choose a Mercurial repository that represents your central “official” source tree. This will be the same repository that your buildslaves will eventually pull from. Install Buildbot on the machine that hosts this repository, using the same version of python as Mercurial is using (so that the Mercurial hook can import code from buildbot). Then add the following to the .hg/hgrc file in that repository, replacing the buildmaster hostname/portnumber as appropriate for your buildbot:

     [hooks]
     changegroup.buildbot = python:buildbot.changes.hgbuildbot.hook
     
     [hgbuildbot]
     master = buildmaster.example.org:9987

(Note that Mercurial lets you define multiple changegroup hooks by giving them distinct names, like changegroup.foo and changegroup.bar, which is why we use changegroup.buildbot in this example. There is nothing magical about the “buildbot” suffix in the hook name. The [hgbuildbot] section is special, however, as it is the only section that the buildbot hook pays attention to.)

Also note that this runs as a changegroup hook, rather than as an incoming hook. The changegroup hook is run with multiple revisions at a time (say, if multiple revisions are being pushed to this repository in a single hg push command), whereas the incoming hook is run with just one revision at a time. The hgbuildbot.hook function will only work with the changegroup hook.

If the buildmaster PBChangeSource is configured to require sendchange credentials then you can set these with the auth parameter. When this parameter is not set it defaults to change:changepw, which are the defaults for the user and password values of a PBChangeSource which doesn't require authentication.

     [hgbuildbot]
     master = buildmaster.example.org:9987
     auth = clientname:supersecret

You can set this parameter in either the global /etc/mercurial/hgrc, your personal ~/.hgrc file or the repository local .hg/hgrc file. But since this value is stored in plain text, you must make sure that it can only be read by those users that need to know the authentication credentials.

The [hgbuildbot] section has two other parameters that you might specify, both of which control the name of the branch that is attached to the changes coming from this hook.

One common branch naming policy for Mercurial repositories is to use it just like Darcs: each branch goes into a separate repository, and all the branches for a single project share a common parent directory. For example, you might have /var/repos/PROJECT/trunk/ and /var/repos/PROJECT/release. To use this style, use the branchtype = dirname setting, which simply uses the last component of the repository's enclosing directory as the branch name:

     [hgbuildbot]
     master = buildmaster.example.org:9987
     branchtype = dirname

Another approach is to use Mercurial's built-in branches (the kind created with hg branch and listed with hg branches). This feature associates persistent names with particular lines of descent within a single repository. (note that the buildbot source.Mercurial checkout step does not yet support this kind of branch). To have the commit hook deliver this sort of branch name with the Change object, use branchtype = inrepo:

     [hgbuildbot]
     master = buildmaster.example.org:9987
     branchtype = inrepo

Finally, if you want to simply specify the branchname directly, for all changes, use branch = BRANCHNAME. This overrides branchtype:

     [hgbuildbot]
     master = buildmaster.example.org:9987
     branch = trunk

If you use branch= like this, you'll need to put a separate .hgrc in each repository. If you use branchtype=, you may be able to use the same .hgrc for all your repositories, stored in ~/.hgrc or /etc/mercurial/hgrc.

As twisted needs to hook some Signals, and that some web server are strictly forbiding that, the parameter fork in the [hgbuildbot] section will instruct mercurial to fork before sending the change request. Then as the created process will be of short life, it is considered as safe to disable the signal restriction in the Apache setting like that WSGIRestrictSignal Off. Refer to the documentation of your web server for other way to do the same.

The category parameter sets the category for any changes generated from the hook. Likewise, the project parameter sets the project. Changes' repository attributes are formed from the Mercurial repo path by stripping strip slashes.