From a495a8b4af8715ffac1a8c1619256b7bc47d7c3c Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Tue, 1 Aug 2017 16:03:25 -0400 Subject: Add README for a git_multimail.py plugin Since supporting git_multimail.py is quite complex, this README provides documentation. Eventually it might do well to be converted to a chapter in the admin manual. --- plugins/README.multimail | 161 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 plugins/README.multimail diff --git a/plugins/README.multimail b/plugins/README.multimail new file mode 100644 index 0000000..1b52f7d --- /dev/null +++ b/plugins/README.multimail @@ -0,0 +1,161 @@ +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. -- cgit v1.2.1