gh-notifications

Notifications for GitHub Webhook events

About

This script is used to "catch" and process GitHub Webhook events, and generate an useful email from the payload.

Dependencies

This script is written in Python.

The following modules are used:

• sys
• os
• json
• smtplib
• email.message
• email.mime.text
• email.utils
• subprocess

Install Webhook

In the Repository settings, click on "Webhooks". Click "Add webhook."

As "Payload URL" specify the website which uses this script here.

Content type: application/x-www-form-urlencoded

Specify a Secret.

Enable SSL verification (you better have this enabled for your webhook service).

Specify that all events (not just commits) shall trigger the webhook.

Finally, click "Add webhook".

Using 'webhook' with this script

The webhook tool can be used to receive GitHub Webhooks. I blogged about the setup here.

The following is an example how to setup webhook:

[
  {
    "id": "github",
    "execute-command": "/path/to/github.py",
    "command-working-directory": "/tmp",
    "pass-arguments-to-command":
    [
        {
          "source": "string",
          "name": "[email protected]"
        },
        {
          "source": "string",
          "name": "[email protected]"
        },
        {
          "source": "header",
          "name": "X-Github-Event"
        },
        {
          "source": "entire-payload"
        }
    ],
    "response-message": "OK",
    "trigger-rule":
    {
        "match":
        {
            "type": "payload-hash-sha1",
            "secret": "secret",
            "parameter":
            {
                "source": "header",
                "name": "X-Hub-Signature"
            }
        }
    }
  }
]

A few things need to be replaced:

• "[email protected]": that is the email address used as "From" in any email
• "[email protected]": that is the email receiver
• "/path/to/github.py": the path to the github.py script
• "id": that is the URL path for webhook
• "secret": the secret entered into the GitHub webhook page

Recognized GitHub events

Currently this script recognizes the following GitHub events:

• ping
• push
• repository
• watch
• star
• issues
• member
• commit_comment
• issue_comment
• fork
• pull_request
• pull_request_review
• pull_request_review_thread
• pull_request_review_comment
• meta
• create
• delete (branch)
• repository_vulnerability_alert
• project
• label
• check_run
• check_suite
• workflow_job
• workflow_run
• deploy_key
• branch_protection_rule
• dependabot_alert
• status

It will generate an email with details about unknown events.

pre-commit hook

The included file pre-commit can be placed in .git/hooks and will ensure that the README.md is updated if changes are applied to the Python script.