Git-Observer

Discord bot for notifying on github events

⚠️ This bot is meant to write messages to only one channel (implementing this for multiple projects/channels is a mess so...) ⚠️

⚠️ Even bigger warning: Sometime, I will do a nice installation script, but until then you'll have to follow the long installation process ⚠️

⚠️ I published this project because some friends wanted to use my bot for themselves, but I did not intend to do something generic. A lot of paths and other stuff were hard-coded (bad habit, I know...). So you'll have to change them yourselves, although I'll guide you through this process, don't worry. ⚠️

This project is meant to be installed on a linux server.

How does it work ?

Like this :

Loop #1
Event on your github repository >--git event-- ...
... ----> Github Hook Server >--webhook------- ...
... ----> nginx server >---local proxy pass--- ...
... ----> hook listener >-------write json on disk

Loop #2
discord bot script listener >--file content--- ...
... ----> webhook formatter >----printable---- ...
... ----> writing the pretty-msg to discord server

Installation

Since this project is split into two distinct parts (discord bot and webhook listener), the installation process is a bit long. But everything is pretty straightforward. First, please clone the repository :

git clone https://github.com/Nicolas-Reyland/Git-Observer
cd Git-Observer

Setting up the github webhooks listener

Setting up github webhooks in github

Setting up webhooks on your github repos is very simple! Please refer to one of these guides :

• Unofficial tutorial by bitrise.io
• Unofficial tutorial by IBM
• Official gh webhook page (you just need to enable webhooks, there is no need to read the whole doc)

When adding your webhook, please select the following Content Type: application/json ⚠️ The webhook secret should be remembered; we will need it later. You can use something like "https://your-domain-or-ip-address/github-webhooks" for the payload url.

Installing the dependencies for the webhooks listener

The gh webhook listener runs on ruby, using a library called Sinatra :

sudo apt update
sudo apt-get install ruby-dev build-essential -y
sudo gem install sinatra --no-document # the '--no-document' is optional

Setting up the listener

Here, you have to make some choices.

# you should be in the Git-Observer repo dir
cp -r ./webhook-listener path-to-the-listenenr-repo # (you have to create it)
cd path-to-the-listenenr-repo # you can also stay inside the github repo and not create a new dir

You should see myapp.rb when typing ls -l. Now, please enter the following commands :

mkdir hook-dumps # this is your hook-dump directory (please remember this)
./update-gh-hook-ip-list # if this fails, it should not be fatal

Changing the contents of the ruby script

Please open the script myapp.rb in you favorite text editor (e.g. vim myapp.rb). Now, on line 17, you can change the GH_WH_LISTENER to the absolute path of the current directory. The result yould look like so: /home/nicolas/gh-wh-listener. The whole line should look like this:

file = File.open("/home/nicolas/gh-wh-listener/hook-dumps/#{date.to_i.to_s}.json", "w") {

Setting up the discord bot

Setting up the bot dir

Create the discord bot directory like this :

cp -r discord-bot your-discord-bot-dir # you can also stay inside the github repo

Creating a discord bot

Creating a discord bot is very straightforward. Please follow one of the following tutorials:

• [https://discordpy.readthedocs.io/en/stable/discord.html](Unofficial tutorial by discord.py)
• [https://www.digitaltrends.com/gaming/how-to-make-a-discord-bot/](Unofficial tutorial by digitaltrends.com) (you do not need to go further than the fourth step)

For the permissions, please refer to the content of this file (although selecting "administrator rights" is quicker).

Then, you should copy the discord bot token to the your-discord-bot-dir/discord-bot-token.txt (in this repo).

Installing the dependencies for the discord bot

You need python3.9 (or a higher version) and the discord.py dependecy.

sudo apt update
sudo apt install python3-dev
sudo apt install python3.9
pip install discord.py

Changing the bot scripts

In the your-discord-bot-dir/cogs/git-notifier.py file, change the following :

• on line 11, add path to the hook-dumps directory, which was setup in the ruby listener installation step
• on line 12, add the id of the discord channel which you want the bot to write messages in (as an int, not a str)

Creating the appropriate linux services

Fist of all, please copy the service files to the correct location :

# inside the repo dir
cp -i services/*.service /etc/systemd/system/

Changing the content of the ruby listener service file

Edit /etc/systemd/system/github-webhooks-sudoku-sinatra.service like so :

• on line 8, edit the string and replace it by your github webhook secret (you chose this during the webhook creation in github)
• on line 11, add your user name
• on line 12, change the working directory to the github webhook listener
• on line 13, add the full path to the myapp.rb script

Changing the content of the discord bot service file

Edit /etc/systemd/system/git-observer-bot.service like so :

• on line 10, add your user name
• on line 11, add the discord bot directory path
• on line 12, add the full path to the bot.py script

Optional steps

If you wish these services to be started system boot time, you can enter these commands :

sudo systemctl enable github-webhook-listener.service
sudo systemctl enable git-observer-bot.service

Redirecting your requests to the ruby server

I will assume that you are using nginx on your linux server. The steps are not that different when using a different web server service. In you default web site script (/etc/nginx/sites-available/default.00 or something), add these line in the main server block :

location /github-webhooks {
  # you could restrict the ip addresses that access this to the github hooks url list
  # see webhook-listener/update-gh-hook-ip-list and webhook-listener/github-hooks-ip-list
  proxy_pass http://localhost:4567;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
}

Think to verify that your file valid :

sudo nginx -t

And reload the nginx service :

sudo systemctl reload nginx

Post-installation & Usage

To start the application, you can enter these commands :

sudo systemctl start github-webhook-listener.service
sudo systemctl start git-observer-bot.service

To modify the output of the bot, you can modify the your-discord-bot-dir/cogs/webhook_formatter.py file.

Todo:

• local socket communication instead of new-file-detection method (makes it one-loop arch instead of 2-loop)
• propoer, generic values instead of hard-coded ones
• can write to multiple channels, one per repository
• installation script
• remove the nginx redirection -> directly listen to webhooks in the ruby script