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 setup.py 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:

  [/path/to/repository/.git]
  bugzilla_url: https://repo.example.com/bugzilla/
  bugzilla_user: foo@example.com
  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:

post-receive:

#!/usr/bin/python
from gitzilla.hooks import post_receive
post_receive("https://repo.example.com/bugzilla", "username", "password")

update:

#!/usr/bin/python
from gitzilla.hooks import update
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. If that is provided, bugzilla credentials MUST be provided as well.

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.

[/path/to/repository/.git]
bugzilla_url: https://repo.example.com/bugzilla/
bugzilla_user: foo@example.com
bugzilla_password: blahblah
allowed_bug_states: NEW, ASSIGNED, REOPENED
logfile: /var/log/gitzilla.log
loglevel: info

Mandatory parameters

• bugzilla_url
• bugzilla_user
• bugzilla_password

Optional parameters

• 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. If this is set, working bugzilla credentials are required (see security note).

• 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 is required to contain a username/password for bugzilla. If you think this is a problem, you could put in dummy values. In that case however, users MUST put their own credentials in their ~/.gitzillarc files if the update hook is being used with the allowed_bug_states option set. If that is not the case, users can get away by not having their credentials available, and their commits would not show up in bugziila comments.

To summarize:

• Either put working Bugzilla credentials in the global config. These will be used when the users don't provide with their own via the user specific files.
• If putting in Bugzilla credentials is seen as a risk, or if the users are to be forced to provide their own credentials via ~/.gitzillarc, you MUST use the update hook with the allowed_bug_states option set to some bug statuses.
• If /etc/gitzillarc does not have correct Bugzilla credentials and the update hook is not used with the allowed_bug_states option set, users who do not provide correct credentials via ~/.gitzillarc will be able to skip the Bugzilla comment addition step. Their commits will still be accepted though (depending on the update hook).