223 lines
6.6 KiB
Plaintext
223 lines
6.6 KiB
Plaintext
|
|
========
|
|
GitZilla
|
|
========
|
|
|
|
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.
|
|
|
|
|
|
Usage
|
|
.....
|
|
|
|
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.
|
|
|
|
|
|
Configuration
|
|
.............
|
|
|
|
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
|
|
http://docs.python.org/library/configparser.html). A sample configuration
|
|
looks 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
|
|
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``, ``bugzilla_user`` and ``bugzilla_password``
|
|
parameters.
|
|
|
|
The user specific files are entirely optional.
|
|
|
|
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).
|
|
|
|
|
|
Requirements
|
|
............
|
|
|
|
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 http://github.com/ColdWind/pybugz/
|
|
and http://github.com/ColdWind/pybugz/downloads/
|
|
|
|
|
|
Download
|
|
........
|
|
|
|
GitZilla is hosted at GitHub : http://github.com/gera/gitzilla
|
|
|
|
You can access the downloads at : http://github.com/gera/gitzilla/downloads
|
|
|
|
The download page contains a .deb which should work on Debian and Ubuntu
|
|
systems.
|
|
|
|
|
|
|