Flask extension for creating Github Apps
Project description
Flask-GithubApplication
Flask extension for rapid Github app development in Python, in the spirit of probot
GitHub Apps help automate GitHub workflows. Examples include preventing merging of pull requests with "WIP" in the title or closing stale issues and pull requests.
Getting Started
Installation
To install Flask-GitHubApplication:
pip install flask-githubapplication
Create GitHub App
Follow GitHub's docs on creating a github app.
You can, in principle, register any type of payload to be sent to the app!
Once you do this, please note down the GitHub app Id, the GitHub app secret, and make sure to create a private key for it! These three elements are required to run your app.
Build the Flask App
The GithubApp package has a decorator, @on
, that will allow you to register events, and actions, to specific functions.
For instance,
@github_app.on('issues.opened')
def cruel_closer():
#do stuff here
Will trigger whenever the app receives a Github payload with the X-Github-Event
header set to issues
, and an action
field in the payload field containing opened
Following this logic, you can make your app react in a unique way for every combination of event and action. Refer to the Github documentation for all the details about events and the actions they support, as well as for sample payloads for each. You can also have something like
@github_app.on('issues')
def issue_tracker():
#do stuff here
The above function will do stuff here
for every issues
event received. This can be useful for specific workflows, to bring developers in early.
Inside the function, you can access the received request via the conveniently named request
variable. You can access its payload by simply getting it: request.payload
You can find a complete example (containing this cruel_closer function), in the samples folder of this repo. It is a fully functioning flask Github App.
Run it locally
For quick iteration, you can set up your environment as follows:
EXPORT GITHUBAPP_SECRET=False # this will circumvent request verification
EXPORT FLASK_APP=/path/to/your/flask/app.py # the file does not need to be named app.py! But it has to be the python file that instantiates the Flask app. For instance, samples/cruel_closer/app.py
This will make your flask application run in debug mode. This means that, as you try sending payloads and tweak functions, fix issues, etc., as soon as you save the python code, the flask application will reload itself and run the new code immediately. Once that is in place, run your github app
flask run
Now, you can send requests! The port is 5000 by default but that can also be overridden. Check flask run --help
for more details. Anyway! Now, on to sending test payloads!
curl -H "X-GitHub-Event: <your_event>" -H "Content-Type: application/json" -X POST -d @./path/to/payload.json http://localhost:5000
Install your GitHub App
Settings > Applications > Configure
If you were to install the cruel closer app, any repositories that you give the GitHub app access to will cruelly close all new issues, be careful.
Deploy your GitHub App
Bear in mind that you will need to run the app somewhere. It is possible, and fairly easy, to host the app in something like Kubernetes, or simply containerised, in a machine somewhere. You will need to be careful to expose the flask app port to the outside world so the app can receive the payloads from Github. The deployed flask app will need to be reachable from the same URL you set as the webhook url
. However, this is getting a little bit into Docker/Kubernetes territory so we will not go too deep.
Usage
GitHubApp
Instance Attributes
payload
: In the context of a hook request, a Python dict representing the hook payload (raises a RuntimeError
outside a hook context).
client
: In the context of a hook request, a GhApi client authenticated as the app installation (raises a RuntimeError
outside a hook context.)
installation_token
: The token used to authenticate as the app installation. This can be used to call api's not supported by GhApi
like Github's GraphQL API
Configuration
GITHUBAPP_ID
: GitHub app ID as an int (required). Default: None
GITHUBAPP_KEY
: Private key used to sign access token requests as bytes or utf-8 encoded string (required). Default: None
GITHUBAPP_SECRET
: Secret used to secure webhooks as bytes or utf-8 encoded string (required). Set to False
to disable
verification.
GITHUBAPP_URL
: URL of GitHub instance (used for GitHub Enterprise) as a string. Default: None
GITHUBAPP_ROUTE
: Path used for GitHub hook requests as a string. Default: '/'
You can find an example on how to init all these config variables in the cruel_closer sample app
Cruel Closer
The cruelcloser sample app will use information of the received payload (which is received every time an issue is opened), will _find said issue and close it without regard.
Credits:
Much of this project originated from flask-github. It currently uses Github3.py which was missing many endpoints and lacked good documentation.
This version will be using GhApi instead since it has 100% api coverage.
Due to the breaking nature and downstream effects of this changes, a new project was created.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for Flask-GitHubApplication-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a97e6a8d5f5942d4d897ac83dc944485e4ff0413eded4c8542d5e210bb135a41 |
|
MD5 | c42e12aa29c931a24e2fa0ddbf629d39 |
|
BLAKE2b-256 | 89046dfdce58b478bbaa1454e4bd1e77dc03989d8447c526aafc4d5e803d1a11 |
Hashes for Flask_GitHubApplication-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c755189b4157f2ad5715f0e5585665553252ce0aa3f2c8d0c9548ab9ed2fe7e |
|
MD5 | 08d5b53372b85f508d630c3828fa1a71 |
|
BLAKE2b-256 | 3f1a57e4247f55114866e02e5cb0a0e4b1c1ec7e304f1b8f3d8301ed39647ff0 |