: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:
application/json
. The application/x-www-form-urlencoded
content type is not supported yet.=== 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:
=== 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:
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:
For example, the following URLs can show numbers on exceptions/errors occurred and how long it took while sending emails:
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.