Using Git Multimail with Gitano =============================== Gitano provides a plugin for use with `git_multimail.py`. In order to use it a number of preparatory steps must be taken. Sysadmin responsibilities ------------------------- In order to enable the multimail capability in Gitano the plugin must be installed (it will be, by default, but some distributions may put it in a separate package). Also there must be a copy of `git_multimail.py` on the system somewhere. It may be available in the contrib part of the distribution Git package, otherwise it can be acquired from: https://git.kernel.org/pub/scm/git/git.git/plain/contrib/hooks/multimail/git_multimail.py?id=HEAD The sysadmin must become the unix user that Gitano is running as, and run the following command to enable the plugin `git_multimail.py` $ git config --global gitano.multimail.location /path/to/wherever/git_multimail.py Without this setting, the multimail plugin will be entirely disabled. The actual `git_multimail.py` must be executable and must have any dependencies met on the system. In addition, the sysadmin will want to configure things like `multimailhook.mailer` and associated settings such that `git_multimail.py` will be able to send emails out. Gitano-Admin responsibilities ----------------------------- ### Rules Once the multimail plugin is permitted to run for the site, it also needs to use the Gitano ACL system to check for permission to run on the given repository. Note that control over which refs it runs for is independent of this ACL check. In order to check for permission, the multimail plugin will request, of the repository in question, an ACL check of the form: * `source`: `plugin_multimail` * `repository`: `path/to/repo` * `operation`: `multimail` * `user`: `gitano/multimail` * The usual `config/` etc are available too If that ACL check results in an 'allow' then the multimail plugin will run the `git_multimail.py` identified in the Git config from above. If admins do not wish to grant the capability to all repositories, they might consider a rule (before the `include main` in `core.lace`) along the lines of: deny "Repositories may not authorise multimail" [operation is multimail] More complex rule examples may be found on the Gitano wiki. It's also worth noting that if you are running your instance primarily from the gitano-admin user (which is bad and wrong, but some people do do it) then you will need to add any denial rules very early since otherwise the allow "Administrators can do anything" will kick in and could cause unexpected mails to be sent. ### Config In order to permit a further level of control and flexibility for the multimail plugin, configuration is read from four places and combined in order to create the configuration which will be passed to `git_multimail.py`. Firstly there are some defaults in the multimail plugin. These are there to mostly prepare `git_multimail.py` for the fact that it is running under Gitano. Secondly, the `project.conf` of `gitano-admin` is consulted and anything in a `defaults.multimail.` prefix is copied into the configuration, overriding any defaults from the plugin itself. Thirdly, the `project.conf` of the repository in question is consulted, and anything in the `multimail.` prefix is copied into the configuration, overriding the previous two. Finally, the `project.conf` of `gitano-admin` is consulted a second time, and anything in a `override.multimail.` prefix is copied into the configuration, permitting the gitano site administrator to override anything they choose. This combined configuration is then passed in as additional configuration items when `git_multimail.py` is invoked. In order to protect against wrongdoings and potential attack vectors, the names of the configuration items (and note the case, since that's important) which will be honoured by the config are: * `mailingList`: the default location for all emails unless overridden * `refchangeList`: the location to which reference change summaries are sent * `announceList`: the location for tag notification to be sent * `commitList`: the location where actual commit diffs are sent * `from`: the address from which the mails will be sent. This takes content of the form `Real Name ` and defaults to the real name and email address of the entity pushing to the Gitano server. * `announceShortLog`: if set to `true` this means announce mails include a short log of changes * `commitBrowseURL`: The url format string which will be passed for configuring the email bodies to include a URL to the commit. This is of the form `https://some.server/somewhere/%(id)s` If the string contains the sequence `%(repo)s` then the repository path will be substituted, allowing for site defaults if there is a site cgit. * `refchangeShowGraph`: if set to `true`, show the git graph in the ref change summary mail * `refchangeShowLog`: if set to `true`, show a patch log in the ref change summary mail * `administrator`: if set, this will go into the footer as the administrator of the site. * `emailPrefix`: if set, is a summary prefix. Using `%(repo_shortname)s` will use a shortened repository name automatically * `refFilterInclusionRegex`, `refFilterExclusionRegex`, `refFilterDoSendRegex`, `refFilterDontSendRegex`: These configure the refs which `git_multimail.py` will be sensitive to. * `verbose`: if set to `true` will cause `git_multimail.py` to be somewhat verbose and say what it's up to. * `stdout`: if set to `true`, will send the content to the output (returned to the person pushing) instead of emailing it, so that it can be checked prior to enabling the feature properly In general, see `git_multimail.py`'s documentation for further information on the above options. The multimail configuration is structured as above to allow maximum flexibility combined with the ability to control almost all aspects of the multimail behaviour with the 'config' command (which can be ACL filtered and delegated). Regardless of any attempts to set it in config, the `repoName` configuration value will be set by the plugin last and thus are not overridable. Repo owner responsibilities --------------------------- If the gitano-admin has delegated permission to switch multimail on and off, then the repo owner must set a Lace rule to allow it. In addition, any configuration for multimail which is necessary for the repo should be set in the configuration for it. If nowhere sets any of the address options, then the multimail plugin will not invoke `git_multimail.py` at all. Hooks ----- Just before the multimail plugin applies the above whitelist to the configuration data, it will run a hook called 'multimail' whose API is: local repo, updates, confbits = ... -- make changes to confbits which is a key/value table of configs If the hook fails then the plugin will abort. If the hook alters the `confbits` table then the changes will be reflected in the invocation of `git_multimail.py` and if the plugin alters the updates table, then those changes will be reflected also. As such, the hook can choose to erase some ref changes from the invocation if they so choose.