index.py is a python CGI script that provides a Webhook to be used as a github hook endpoint to send mail to a set of email addresses when specific GitHub events happen
index.py is a python CGI script that provides a Webhook to be used as a github hook endpoint to send mail to a set of email addresses when specific events (e.g. push, new issues, etc) happen in specific repos.
It can also be used without a hook to send a digest of activity across a set of defined repositories for a given period. In that mode, it is limited to 300 events in the said period for a given repo.
It can also be used as a W3C hook endpoint to send mail when TR documents get published.
The set of mailing lists, repos / TR documents and events is configured in a JSON file, named mls.json
that lives in the same directory as the webhook, with the following structure:
{
"[email protected]": {
"githubaccount/repo": {
"events": ["issues.opened", "issues.closed", "issue_comment.created", "pull_request.opened", "pull_request.labeled"],
"eventFilter": {"label":["important"]},
"branches": {
"master": ["push"]
}
}
},
"[email protected]": {
"http://www.w3.org/TR/wake-lock": {
"events": ["tr.published"]
}
},
"[email protected]": {
"digest:tuesday": [
{
"repos": ["githubaccount/repo", "githubaccount/repo2"]
},
{
"repoList": "https://example.org/repos.json"
},
{
"topic": "All of repo4 and some of repo3",
"sources": [
{
"repos": ["githubaccount/repo3"],
"eventFilter": {"label": ["enhancement"]}
},
{
"repos": ["githubaccount/repo4"]
}
]
}
]
}
}
In other words:
events
is an array of Github events applicable to the repo as a whole; only events in that array will be notifiedeventFilter
is an optional set of filters that are applied to the events above; at the moment, label
and notlabel
filters are defined, which means that only events that are associated with one of the said labels (defined as an array) will be notified (resp. only events that aren't associated with any of the labels)branches
allows to describe events that are applicable at the branch level rather than the whole repo (e.g. "push")events
field, with "tr.published"
currently the only supported event.w3c/webrtc-pc
) and/or a "repoList" field with an URL pointing a JSON area of repository fullnames (which gets combined with the list in repos
if it is fetched successfully), and optionally an "eventFilter" field (which, as above, has label
and notlabel
as possible filters at the moment) that applies to all the said reposOnly events for which templates have been defined (in the templates/generic
directory) will be notified. Each mail target can have customized templates by creating an [email protected]
directory in templates/mls
and having a file named after the event. Templates use Mustache-based pystache as their engines and are fed with payload data from the event. The first line of the template is used as the subject of the email.
In addition to configuring targets of notifications, an instance of this webhook needs to define a config.json
file with the SMTP host, the address from which messages will be sent, and set a GitHub OAUTH token that can be used to retrieve information via the GitHub API.
See also how to make use of the W3C instance of this service.
Run the test suite with:
python test_webhook.py
A typical test consists of:
test_webhook.py
SendEmailGithubTests
that binds the event name, with the JSON file, and the email message