GitHub events emailer

The application can keep you up to date with what’s going on in git repositories hosted at GitHub (public or self-hosted enterprise) or you can even perform an instant review of your peers. It works by accepting events from GitHub webhooks or polling events from GitHub, parsing events, when needed retrieving additional information on commits, tags, users, etc. Then composes emails and sends them out to a recipient via a configured SMTP server.

Table of Contents

• Build
• Usage
  • Setting up a Webhook
  • Supported events
  • Configuration
  • Run
  • Using HTTPS
  • Monitoring
• Questions

Build

./gradlew clean build

Usage

Setting up a Webhook

https://developer.github.com/webhooks/creating/

The application supports webhooks that are configured in the following way:

• Payload URL

  • It is set with plain HTTP with URL any path. For secured connection, see section Using HTTPS.

• Content type

  • It is set to application/json. The application/x-www-form-urlencoded content type is not supported yet.

• Secret

  • Could be left empty or set with any value. Payloads from github are not validated yet.

• Events

  • On supported events, see section Supported events. However, the application will not crash if receive unexpected events.

Supported events

• Pushes

  A single or multiple (as per number of commits in a push) emails will be sent that contains the following:

  • Organization/user/repository/branch name

  • Pusher name

  • Commit URL at Github

  • Commit author and date

  • Commit message

  • Author and date

  • Whole commit diff including a list of changed files

• Branch or tag creation

  An email will be sent that contains the following:

  • Organization/user/repository name

  • Tagger name

  • Annotated or lightweight tag was created

  • Tag name

  • User who created branch

• Branch or tag deletion

  An email will be sent that contains the following:

  • Organization/user/repository name

  • Tag or branch name

  • User who deleted branch or tag

• Fork

  An email will be sent that contains the following:

  • User who forked a repository

  • Fork name and url

Configuration

See the configuration file for details.

Important

Configuration options whose value is change_me must be explicitly configured before running the application in standalone mode or as docker container.

Run

Standalone

Run the jar file as the following:

nohup java -jar github-events-emailer-<version>-boot.jar &

When you run in the standalone mode, the configuration files are loaded from the jar file. To override configuration parameters, just place a copy of application.properties the file where Spring Boot can find it.

Docker

Start a container instance as the following:

docker run -p 8080:8080 -e "github.oauthToken=<token>" -e "..." docker.io/zobkov/github-events-emailer

You can adjust the configuration of the instance by passing one or more environment variables on the docker run command line. See the list of available variables in application.properties.

Kubernetes

To deploy the application on kubernetes cluster you can refer to several example manifests at wiki page.

Using HTTPS

The application itself supports accept connections with the plain HTTP only. However, the application can be put behind a reverse-proxy with configured HTTPS transport to enable secured connections.

The following are examples of reverse-proxies:

• Traefik

• Envoy

• Caddy

• Nginx

Monitoring

The application exposes the Sprint Boot Actuator endpoints over HTTP. This includes registered additional metrics besides standard ones:

• CamelExchangesFailed - The metric allows to understand on which processing step and how many times exceptions/errors occurred

• CamelMessageHistory - The metric allows to get insight on how long it took to process this or that step

For example, the following URLs can show numbers on exceptions/errors occurred and how long it took while preparing emails based on recieved github events:

• http://localhost:8081/actuator/metrics/CamelExchangesFailed?tag=routeId:translator

• http://localhost:8081/actuator/metrics/CamelMessageHistory?tag=nodeId:translate-github-events

For example, the following URLs can show numbers on exceptions/errors occurred and how long it took while sending emails:

• http://localhost:8081/actuator/metrics/CamelExchangesFailed?tag=routeId:email-sender

• http://localhost:8081/actuator/metrics/CamelMessageHistory?tag=nodeId:send-email

An endpoint for Prometheus is also exposed, so you can use a Prometheus-Grafana stack to monitor the application. To experiment with this, you can perform the following steps:

1. Get a Prometheus-Grafana stacks: https://github.com/vegasbrianc/prometheus

2. Add a scrape_config like the one shown in Spring Boot Actuator documentation to add to prometheus.yml

3. Start the Prometheus-Grafana stack

4. Import a simple dashboard that includes monitoring of the metrics listed above with the steps described in Grafana documentation

Questions

If you have any questions, feel free to open GitHub issue.