README.md

github-email-notifications

Better email notifications from github with clear, concise, and readable messages.

Simple python web application for Heroku that accepts github webhooks for "push" events and generates a clear, concise, and readable email message.

It is designed to meet the Chapel team's needs, as the email hook provided by github is rather noisy and it looks unlikely to change. The Chapel project uses the feature branch workflow, and always includes a nice summary in the merge commit messages. So, the merge message (actually the head commit in the push event) is the only one included in the email.

Heroku Setup

Create the app, enable papertrail to record logs, and set the configuration variables.

heroku create [<app_name>]
heroku addons:add papertrail
heroku config:set GITHUB_COMMIT_EMAILER_SEND_FROM_AUTHOR=<true>
heroku config:set GITHUB_COMMIT_EMAILER_SENDER=<sender_email>
heroku config:set GITHUB_COMMIT_EMAILER_RECIPIENT=<recipient_email>
heroku config:set GITHUB_COMMIT_EMAILER_SECRET=<the_secret>

If GITHUB_COMMIT_EMAILER_SEND_FROM_AUTHOR is set (to any value), the pusher name and email combination will be used as the "From" address instead of the configured sender value. If a reply-to is configured, see below, that will be added regardless of this setting.

Optionally, a reply-to address can be configured with the following config. If not set, no reply-to header is set so the sender address will be used as reply address.

heroku config:set GITHUB_COMMIT_EMAILER_REPLY_TO=<reply_to_email>

Optionally, an "Approved" header value can be configured. The Approved header automatically approves the messages for a read-only or moderated mailing list.

heroku config:set GITHUB_COMMIT_EMAILER_APPROVED_HEADER=<approved_header>

SendGrid Setup

Enable addon, and disable the plain text to html conversion:

heroku addons:add sendgrid
heroku addons:open sendgrid

• Go to "Global Settings".
• Check the "Don't convert plain text emails to HTML" box and "Update".

Rollbar Setup

Rollbar provides error tracking, in case anything unexpected happens. Enable the addon and optionally set the environment name.

heroku addons:add rollbar

Optionally, set the environment name for rollbar. This is probably only necessary if you have multiple environment configured to use rollbar.

heroku config:set GITHUB_COMMIT_EMAILER_ROLLBAR_ENV=<env_name>

GitHub Setup

Add webhook to repo to use this emailer. Be sure to set the secret to the value of GITHUB_COMMIT_EMAILER_SECRET. The webhook URL is <heroku_url>/commit-email and it must send "push" events. Show the heroku app url with:

heroku domains

Development

To develop and test locally, install the Heroku Toolbelt, python dependencies, create a .env file, and use foreman start to run the app.

• Install python dependencies (assuming virtualenvwrapper is available):

mkvirtualenv github-email-notifications
pip install -r requirements.txt

• Create .env file with chapel config values:

GITHUB_COMMIT_EMAILER_SENDER=<email>
GITHUB_COMMIT_EMAILER_RECIPIENT=<email>
GITHUB_COMMIT_EMAILER_SECRET=<the_secret>
ROLLBAR_ACCESS_TOKEN=<rollbar_token>
SENDGRID_PASSWORD=<sendgrid_password>
SENDGRID_USERNAME=<sendgrid_user>

To use the same values configured in heroku:

heroku config --shell > .env

• Run the app, which opens at http://localhost:5000:

foreman start

• Send a test request:

curl -vs -X POST \
  'http://localhost:5000/commit-email' \
  -H 'x-github-event: push' \
  -H 'content-type: application/json' \
  -d '{"deleted": false,
    "ref": "refs/heads/master",
    "compare": "http://compare.me",
    "repository": {"full_name": "test/it"},
    "head_commit": {
      "id": "mysha1here",
      "message": "This is my message\nwith a break!",
      "added": ["index.html"],
      "removed": ["removed.it"],
      "modified": ["stuff", "was", "done"]},
    "pusher": {
      "name": "thomasvandoren",
      "email": "[email protected]"}}'

• Install test dependencies and run the unittests.

pip install -r test-requirements.txt
tox
tox -e flake8
tox -e coverage