1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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 <email@address>` 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.
|
