A Python library to supercharge your GitHub organization with bots and webhooks.

---

FastGitHub is a Python package for FastAPI, offering a GitHub webhooks handler and easy Bot creation utilities, streamlined through recipes for easy operations on Github organizations and repositories.

More informations about Github webhooks and payloads: docs.github.com/en/webhooks/webhook-events-and-payloads

---

Features

• ⚙ Seamless experience: GitHub webhook handler and router classes that just works.
• ⚡️ FastAPI native: Build for FastAPI but can be easily integrate with any WSGI web application framework.
• 🔌 Battery included: Come with a set of built-in recipes for the most common GitHub operations.
• ️⛏ Modularity: Recipes can be easily defined for tailor-made needs.

Requirements

Before installing FastGitHub, ensure you have the following prerequisites:

• Python: Version 3.12 or newer.
• FastAPI: FastGitHub is built to work with FastAPI, so having FastAPI in your project is essential.

️️Installation

Install the package from the PyPI registry.

pip install fastgithub

Usage

FastGitHub usually involves 3 steps to handle GitHub webhooks:

1. Define the recipes you want to use.
2. Attach these recipes to a GithubWebhookHandler.
3. Include a webhook_router in your FastAPI application.

Recipes

To define a Recipe (or GithubRecipe), simply add events property that returns a dict with the events as keys and their methods to execute. Use * to trigger the recipe on any events. When a recipe is expected to fail, use a raise exception, so that the handler can return an error to the FastAPI application.

To use a GithubRecipe, a Github instance from PyGithub is required when instantiating the class. A GithubHelper exists to help you to work with a GitHub repository.

You can also use raw functions, although this is not the best solution.

from collections.abc import Callable

from fastgithub import Recipe, GithubRecipe
from fastgithub.helpers.github import GithubHelper
from fastgithub.types import Payload


class Hello(Recipe):
    @property
    def events(self) -> dict[str, Callable]:
        return {"*": self.__call__}

    def __call__(self, payload: Payload):
        print(f"Hello from: {payload['repository']}")


class MyGithubRecipe(GithubRecipe):
    @property
    def events(self) -> dict[str, Callable]:
        return {"push": self.__call__, "pull_request": self.__call__}

    def __call__(self, payload: Payload):
        gh = GithubHelper(self.github, repo_fullname=payload["repository"]["full_name"])
        gh.raise_for_rate_excess()

        print(f"Hello from {gh.repo.full_name}!")


def very_simple_recipe(payload: Payload) -> None:
    print(f"Hello from: {payload['repository']}")

Available recipes

• AutoCreatePullRequest create a PR when a new branch is pushed.
• LabelsFromCommits add label to a PR using commit messages (a default config is provided).

GitHub recipes can be imported from fastgithub.recipes.github.

Webhook handler

Here's a basic example how to define a GithubWebhookHandler with SHA256 signature verification. Setting signature_verification=None allows you to use the handler without signature verification (which is not at all the recommended way to publish GitHub webhook).

from fastgithub import GithubWebhookHandler, SignatureVerificationSHA256

signature_verification = SignatureVerificationSHA256(secret="mysecret")
webhook_handler = GithubWebhookHandler(signature_verification)

You can use the plan method to set recipes to a handler. The listen handler's method allows you attach recipe functions to specific events. The listen method can also be used as a decorator.

webhook_handler.plan([Hello()])

webhook_handler.listen("pull_request", [very_simple_recipe])


@webhook_handler.listen("pull_request")
def another_simple_recipe(payload: Payload) -> None:
    print(f"Hello from: {payload['repository']}")

Webhook router

The webhook_router function returns a fastapi.APIRouter. You can adopte the inner logic of this function to suit your needs.

import uvicorn
from fastapi import FastAPI

from fastgithub import webhook_router

app = FastAPI()
router = webhook_router(handler=webhook_handler, path="/postreceive")
app.include_router(router)

if __name__ == "__main__":
    uvicorn.run(app)

Development

In order to install all development dependencies, run the following command:

uv sync

To ensure that you follow the development workflow, please setup the pre-commit hooks:

uv run pre-commit install

Run the application locally

To test the webhook handler you need to fill an .env file, run:

cp .env.example .env

then run:

docker compose up

Acknowledgements

• Initial ideas and designs were inspired by python-github-webhook and python-github-bot-api.
• README.md layout was inspired by FastCRUD.