probot-emailer

A self-hosted Probot app that delivers push event details to your inbox.

probot-emailer may be used as a self-hosted replacement to the email service that is due to be deprecated on January 31, 2019.

Setup

Overview

1. Register a GitHub App
2. Create a SendGrid API key
   • Domain authentication
3. Deploy to Heroku
4. Update your GitHub App
5. Install your GitHub App
6. Configure your installation

Detail

Register a GitHub App

Register a new GitHub App, providing a GitHub App name, and Homepage URL, and having the following properties:

Permissions

1. Repository contents: Read only

Event subscriptions

1. Push

Webhook URL

For now, use a temporary value, such as http://localhost, we'll come back to this shortly.

Webhook Secret

Be sure to secure your webhooks, to ensure the authenticity of requests from GitHub, by providing a Webhook Secret. Use a random string with high entropy (e.g., by taking the output of ruby -rsecurerandom -e 'puts SecureRandom.hex(20)' at the terminal).

Private key

After creating the GitHub App, be sure to generate a private key, store this in a safe place.

Create a SendGrid API key

Sign up for a free SendGrid account, and create an API key with Mail Send access.

Domain authentication

It is recommended to set up domain authentication in SendGrid in order to signal to email providers that SendGrid has permission to send emails on your behalf.

Deploy to Heroku

Deploy your app to Heroku, populating the Config Vars with your GitHub App's APP_ID, WEBHOOK_SECRET, and PRIVATE_KEY, as well as your SendGrid API key, SENDGRID_APIKEY.

Update your GitHub App

Update your GitHub App's Webhook URL, with the URL of your Heroku app.

Install your GitHub App

Install your GitHub App on the account, or repository that you wish to receive email notifications from.

Configure your installation

Configure the installed app, by creating a .github/probot-emailer.yml file in the root of the repository, for example:

---
addresses: # a list of addresses to send notifications to
  - [email protected]
sender: # the email address of the notification sender (optional)
  name: From
  address: [email protected]

Consider adding your sender.from address as a contact, to avoid it being flagged as spam.

Usage

Once configured, a push to any branch of a configured repository will generate a notification to the addresses defined in your .github/probot-emailer.yml.