:toc: macro

= GitHub events emailer

image:https://github.com/AlexanderZobkov/github-events-emailer/workflows/CI/badge.svg?branch=master["Build Status", link="https://github.com/AlexanderZobkov/github-events-emailer/actions?query=workflow%3ACI"] image:https://img.shields.io/docker/v/zobkov/github-events-emailer?label=docker%20hub["Docker Image Version (latest by date)", link="https://hub.docker.com/r/zobkov/github-events-emailer/tags?page=1&ordering=last_updated"] image:https://img.shields.io/github/license/AlexanderZobkov/github-events-emailer[GitHub]

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.

toc::[]

== 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 <>.
• 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 <>. However, the application will not crash if receive unexpected events.

=== Supported events

• https://developer.github.com/webhooks/event-payloads/#push[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

• https://developer.github.com/webhooks/event-payloads/#create[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

• https://developer.github.com/webhooks/event-payloads/#delete[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

• https://developer.github.com/webhooks/event-payloads/#fork[Fork]

• An email will be sent that contains the following:

• User who forked a repository Fork name and url

=== Configuration

See link:src/main/resources/application.properties[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 link:src/main/resources/application.properties[application.properties] the file where Spring Boot link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config-application-property-files[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 link:src/main/resources/application.properties[application.properties].

==== Kubernetes

To deploy the application on kubernetes cluster you can refer to several example manifests at link:../../wiki/Kubernetes[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:

• link:https://gist.github.com/BretFisher/ede260ba033fabb3993062ae6e766f58[Traefik]
• Envoy
• link:https://caddyserver.com/docs/caddyfile/directives/reverse_proxy[Caddy]
• Nginx

=== Monitoring

The application exposes link:https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-endpoints[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 link:https://prometheus.io/Prometheus[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:

. Get a Prometheus-Grafana stacks: https://github.com/vegasbrianc/prometheus . Add a scrape_config like link:https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-export-prometheus[the one] shown in Spring Boot Actuator documentation to add to prometheus.yml . Start the Prometheus-Grafana stack . Import link:grafana-dashboard.json[a simple dashboard] that includes monitoring of the metrics listed above with the link:https://grafana.com/docs/grafana/latest/dashboards/export-import/#importing-a-dashboard[steps] described in Grafana documentation

image::grafana-dashboard.png[]

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