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);
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;
PyGHee
is available on PyPI, so you can install it with pip
(or another standard Python package installation tool):
pip3 install 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')
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).
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
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!
To run the test suite, use pytest
:
pytest -v -s