Contents
hooks for integrating with the Bugzilla bug tracker
This hook extension adds comments on bugs in Bugzilla when changesets that refer to bugs by Bugzilla ID are seen. The comment is formatted using the Mercurial template mechanism.
The bug references can optionally include an update for Bugzilla of the hours spent working on the bug. Bugs can also be marked fixed.
Four basic modes of access to Bugzilla are provided:
Writing directly to the database is susceptible to schema changes, and relies on a Bugzilla contrib script to send out bug change notification emails. This script runs as the user running Mercurial, must be run on the host with the Bugzilla install, and requires permission to read Bugzilla configuration details and the necessary MySQL user and password to have full access rights to the Bugzilla database. For these reasons this access mode is now considered deprecated, and will not be updated for new Bugzilla versions going forward. Only adding comments is supported in this access mode.
Access via XMLRPC needs a Bugzilla username and password to be specified in the configuration. Comments are added under that username. Since the configuration must be readable by all Mercurial users, it is recommended that the rights of that user are restricted in Bugzilla to the minimum necessary to add comments. Marking bugs fixed requires Bugzilla 4.0 and later.
Access via XMLRPC/email uses XMLRPC to query Bugzilla, but sends email to the Bugzilla email interface to submit comments to bugs. The From: address in the email is set to the email address of the Mercurial user, so the comment appears to come from the Mercurial user. In the event that the Mercurial user email is not recognized by Bugzilla as a Bugzilla user, the email associated with the Bugzilla username used to log into Bugzilla is used instead as the source of the comment. Marking bugs fixed works on all supported Bugzilla versions.
Access via the REST-API needs either a Bugzilla username and password or an apikey specified in the configuration. Comments are made under the given username or the user associated with the apikey in Bugzilla.
Configuration items common to all access modes:
The access type to use. Values recognized are:
| restapi: | Bugzilla REST-API, Bugzilla 5.0 and later. |
|---|---|
| xmlrpc: | Bugzilla XMLRPC interface. |
| xmlrpc+email: | Bugzilla XMLRPC and email interfaces. |
| 3.0: | MySQL access, Bugzilla 3.0 and later. |
| 2.18: | MySQL access, Bugzilla 2.18 and up to but not including 3.0. |
| 2.16: | MySQL access, Bugzilla 2.16 and up to but not including 2.18. |
Template to use when formatting comments. Overrides style if specified. In addition to the usual Mercurial keywords, the extension specifies:
| {bug}: | The Bugzilla bug ID. |
|---|---|
| {root}: | The full pathname of the Mercurial repository. |
| {webroot}: | Stripped pathname of the Mercurial repository. |
| {hgweb}: | Base URL for browsing Mercurial repositories. |
Default changeset {node|short} in repo {root} refers to bug {bug}.\ndetails:\n\t{desc|tabindent}
Configuration items common to XMLRPC+email and MySQL access modes:
Path of file containing Mercurial committer email to Bugzilla user email mappings. If specified, the file should contain one mapping per line:
committer = Bugzilla user
See also the [usermap] section.
The [usermap] section is used to specify mappings of Mercurial committer email to Bugzilla user email. See also bugzilla.usermap. Contains entries of the form committer = Bugzilla user.
XMLRPC and REST-API access mode configuration:
REST-API access mode uses the options listed above as well as:
XMLRPC+email access mode uses the XMLRPC access mode configuration items, and also:
In addition, the Mercurial email settings must be configured. See the documentation in hgrc(5), sections [email] and [smtp].
MySQL access mode configuration:
Activating the extension:
[extensions] bugzilla = [hooks] # run bugzilla hook on every change pulled or pushed in here incoming.bugzilla = python:hgext.bugzilla.hook
Example configurations:
XMLRPC example configuration. This uses the Bugzilla at http://my-project.org/bugzilla, logging in as user bugmail@my-project.org with password plugh. It is used with a collection of Mercurial repositories in /var/local/hg/repos/, with a web interface at http://my-project.org/hg.
[bugzilla]
bzurl=http://my-project.org/bugzilla
user=bugmail@my-project.org
password=plugh
version=xmlrpc
template=Changeset {node|short} in {root|basename}.
{hgweb}/{webroot}/rev/{node|short}\n
{desc}\n
strip=5
[web]
baseurl=http://my-project.org/hg
XMLRPC+email example configuration. This uses the Bugzilla at http://my-project.org/bugzilla, logging in as user bugmail@my-project.org with password plugh. It is used with a collection of Mercurial repositories in /var/local/hg/repos/, with a web interface at http://my-project.org/hg. Bug comments are sent to the Bugzilla email address bugzilla@my-project.org.
[bugzilla]
bzurl=http://my-project.org/bugzilla
user=bugmail@my-project.org
password=plugh
version=xmlrpc+email
bzemail=bugzilla@my-project.org
template=Changeset {node|short} in {root|basename}.
{hgweb}/{webroot}/rev/{node|short}\n
{desc}\n
strip=5
[web]
baseurl=http://my-project.org/hg
[usermap]
user@emaildomain.com=user.name@bugzilladomain.com
MySQL example configuration. This has a local Bugzilla 3.2 installation in /opt/bugzilla-3.2. The MySQL database is on localhost, the Bugzilla database name is bugs and MySQL is accessed with MySQL username bugs password XYZZY. It is used with a collection of Mercurial repositories in /var/local/hg/repos/, with a web interface at http://my-project.org/hg.
[bugzilla]
host=localhost
password=XYZZY
version=3.0
bzuser=unknown@domain.com
bzdir=/opt/bugzilla-3.2
template=Changeset {node|short} in {root|basename}.
{hgweb}/{webroot}/rev/{node|short}\n
{desc}\n
strip=5
[web]
baseurl=http://my-project.org/hg
[usermap]
user@emaildomain.com=user.name@bugzilladomain.com
All the above add a comment to the Bugzilla bug record of the form:
Changeset 3b16791d6642 in repository-name. http://my-project.org/hg/repository-name/rev/3b16791d6642 Changeset commit comment. Bug 1234.