This is the documentation for version 2.0 of GitZilla. For the 1.0 documentation, click here.

GitZilla is Python magic to support Git-Bugzilla integration. There are various ways of using GitZilla.

Note that GitZilla must be installed on the machine receiving commits from everyone - home to the the "official" or the "central" repository.

The GitZilla mailing list is at:


Simple ready scripts

To quickly start using GitZilla:

  • Install GitZilla. You may choose the .deb for easy installation on Debian/Ubuntu systems. Otherwise, just unpack the source and install in the usual setuptools way:

    sudo python install
  • Switch to the hooks directory (/path/to/repository/.git/hooks) and delete the post-receive and update hooks.

  • Link (or copy) the gitzilla provided hooks:

    ln -s $(which gitzilla-post-receive) post-receive
    ln -s $(which gitzilla-update) update
  • Read and edit the config file at /etc/gitzillarc. A simple (and sufficient for most cases) configuration is something like:

    bugzilla_password: blahblah
    allowed_bug_states: NEW, ASSIGNED, REOPENED

    (and even the last item is optional!)

  • Commit away!

Custom GitZilla

If you need the hooks to do other stuff apart from just the Bugzilla integration, you could write your hook as a Python script and leave the Bugzilla stuff to one of the functions from gitzilla.hooks.

In fact with the defaults, the ready scripts are equivalent to the following:


from gitzilla.hooks import post_receive
post_receive("", "username", "password")


from gitzilla.hooks import update

The provided ready scripts do more, but that's just parsing and picking up values from the configuration files.

You could pass a custom bug id extraction regex and your own logging.Logger instance. The update hook function also accepts an array of allowed bug status strings.

Look at the module help for gitzilla.hooks for more information.

Down and dirty

This is an internal-only mode for now. More info when this is stable.


GitZilla uses a global configuration file (at /etc/gitzillarc) as well as per-user configuration files (at ~/.gitzillarc). All the configuration options are picked up from the global config file, and the user specific config is allowed to override only the bugzilla_user and bugzilla_password parameters.

The configuration files themselves are in the ConfigParser format (see A sample configuration looks like:

bugzilla_password: blahblah
user_config: deny
allowed_bug_states: NEW, ASSIGNED, REOPENED
logfile: /var/log/gitzilla.log
loglevel: info

Each git repository on the system MUST have its own section. The global config MUST specify the bugzilla_url parameter.

The user specific files are entirely optional.

Mandatory parameters

  • bugzilla_url

Optional parameters

  • bugzilla_user

    the default username for Bugzilla.

  • bugzilla_password

    the default password for Bugzilla.

  • user_config

    allow/deny user specific bugzilla credentials. The legal values are allow, deny and force. Defaults to allow.

  • allowed_bug_states

    a comma separated set of states that a bug must be in, in order for the commit to be allowed by the update hook.

  • formatspec

    appended to --format=format: and passed to git whatchanged. See the git whatchanged manpage for more info.

  • separator

    a string which would never occur in commit messages. You should not need to set this, as it is already at a safe default.

  • bug_regex

    the (Python) regex for capturing bug numbers. MUST capture all the digits (and only the digits) of the bug id in a named group called bug. This regex is compiled internally with the MULTILINE, DOTALL and IGNORECASE options set. The default regex captures from the following forms:

    • bug 123
    • Bug # 123
    • BUG123
    • bug# 123
    • Bug #123
  • logfile

    the file to log to. MUST be writable by the uid of the git process. In case of ssh pushes, tha usually means it should be writable by all.

  • loglevel

    can be info or debug. Defaults to debug.

Security note

Note that the global config would be readable by all and may contain a bugzilla credentials. If you think this is a problem, you may rely on per-user auth.

If the user_config option is set to allow or force, then auth credentials are picked up from the user specific ~/.gitzillarc file.

If the user_config option is force and the ~/.gitzillarc does not contain bugzilla credentials, then the ~/.bugz_cookie file is used for authentication. To generate a cookie file, a user may use the gitzilla-gencookie script. The cookie validity will of course be dependent on your Bugzilla configuration. If neither credentials nor the cookie file are present (and valid), Bugzilla interactions will fail and the commits will be rejected.

If the user_config option is allow, then user specific credentials are used if available. Only if credentials are unavailable in both the user-specific as well as the systemwide configs, the cookie file is used. This configuration is the default because of the closeness of behaviour from version 1.0.

To summarize:

  • To allow (but not force) users to use their own auth/credentials set user_config to allow and set bugzilla_user and bugzilla_password in the system wide config.
  • To enforce user credentials, set user_config to force and leave the Bugzilla credentials out of the system wide config.
  • To use system wide credentials only, set user_config to deny.
  • To enforce Bugzilla integration, use the update hook. The update hook will check the validity of the credentials (system or user, depending on the config), regardless of the allowed_bug_states option. This is a change in behaviour from version 1.0.


To install and run GitZilla, you need:

  • Python (tested with 2.6.4, should work with >=2.5)
  • pybugz (tested with 0.8.0)

Of course, to make it useful you also need a Bugzilla installation somewhere (not required to be on the same machine). GitZilla has been tested with Bugzilla 3.0.11 and should work with any Bugzilla version supported by pybugz.

The excellent pybugz can be obtained from and


GitZilla is hosted at GitHub :

You can access the downloads at :

The download page contains a .deb which should work on Debian and Ubuntu systems.