PyGHee

PyGHee (pronounced as "piggy") is the GitHub Event Executor, a Python library to facilitate creating a GitHub App implemented in Python to process events from GitHub (like the creation of a pull request, a comment being posted in an issue, etc.).

It takes care of:

• detailed logging of all event activity;
• logging all incoming events in JSON format;
• verifying incoming events to check whether they're indeed coming from GitHub (see also Validating payloads from GitHub);
• collecting event information in an easy to digest format to make processing of events easier;
• handling events by calling the appropriate handle_*_event method (if it is implemented);

Requirements

PyGHee depends on a couple of Python libraries:

• Flask, a simple framework for building complex web applications;
• PyGithub, a Python library to access the GitHub REST API;
• waitress, a production-quality pure-Python WSGI server;

For more specific information, like required versions, see requirements.txt.

In addition:

• a GitHub Personal Access Token (PAT) must be available via the $GITHUB_TOKEN environment variable;
• the GitHub app secret token must be available via the $GITHUB_APP_SECRET_TOKEN environment variable;

Installation

PyGHee is available on PyPI, so you can install it with pip (or another standard Python package installation tool):

pip3 install PyGHee

Using PyGHee

To use PyGHee, you should implement a Python class that derives from the PyGHee class that is provided by the pyghee.lib module, and implement one or more handle_*_event methods that correspond to the types of events you want to act on.

A list of event types is available in the GitHub documentation.

Each handle_*_event is passed a Python dictionary as first argument that contains event information. The location of the PyGHee log file is specified as a second named argument log_file.

So if there would be an event type named example, the corresponding method should be implemented as:

from pyghee.lib import PyGHee

class ExamplePyGHee(PyGHee):

    def handle_example_event(self, event_info, log_file=None):
        # implementation of handling example event goes here

If no handle_*_event method is implemented for a particular event type, a message is logged to signal this. For example:

[20220227-T17:06:35] WARNING: [event id e81030bc-238d-440f-b438-54ba902a2224] No handler found for event type 'issue_comment' (action: created) - event was received but left unhandled!

Your main program should use the create_app function and serve it using waitress:

app = create_app(klass=ExamplePyGHee)
waitress.serve(app, listen='*:3000')

Location of log file

The PyGHee log file is named pyghee.log is located in the directory where the GitHub App is started, and is only appended (not overwritten if it already existed).

Location and structure of event logs

Event data is logged in JSON format in a directory named events_log that is located in the directory where the GitHub App is started.

The logs are organised hierarchically, by event type, event action, date (in that order).

For each incoming event, two JSON files are created, one for:

• the request headers including high-level information like the timestamp on which the event occured, etc.
• the request body including the actual event information (which depends on the event type).

Here's an example of a single event that got logged: an issue commented that was created on 20 Feb 2022 at 14:23:27:

$ ls events_log/issue_comment/created/2022-02-20/
2022-02-20T14-23-27_d3ed7694-8a6c-4008-a93f-b92aa86a95a8_body.json
2022-02-20T14-23-27_d3ed7694-8a6c-4008-a93f-b92aa86a95a8_headers.json

Example

Here's an example of how to use PyGHee.

Copy-paste this into a file named pyghee_example.py:

import waitress

from pyghee.lib import PyGHee, create_app
from pyghee.utils import log

class ExamplePyGHee(PyGHee):

    def handle_issue_comment_event(self, event_info, log_file=None):
        """
        Handle adding/removing of comment in issue or PR.
        """
        request_body = event_info['raw_request_body']
        issue_url = request_body['issue']['url']
        comment_author = request_body['comment']['user']['login']
        comment_txt = request_body['comment']['body']
        log("Comment posted in %s by @%s: %s" % (issue_url, comment_author, comment_txt))
        log("issue_comment event handled!", log_file=log_file)


if __name__ == '__main__':
    app = create_app(klass=ExamplePyGHee)
    log("App started!")
    waitress.serve(app, listen='*:3000')

To run your GitHub App:

• Define environment variables for GitHub Personal Access Token (PAT) and GitHub app secret token:

  export GITHUB_TOKEN=...
  export GITHUB_APP_SECRET_TOKEN=...
  

• Start your GitHub App:

  python3 -m pyghee_example
  

You should see a log file named pyghee.log that is created in the directory where your GitHub App was started from, which includes a message like:

[20220227-T18:54:49] App started!

Test suite

To run the test suite, use pytest:

pytest -v -s