fastgithub 0.0.4

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

FastGitHub

CI/CD
Meta
Package

---

About this project

FastGitHub provides a GitHub webhooks handler for FastAPI to automate your workflows.

FastGitHub also provides sets of automations (named recipes).

More informations about Github webhooks and payloads can be found here.

️️⚙️ Installation

Install the package from the PyPI registry.

pip install fastgithub

⚡ Usage

Example

This is a basic example that handles the creation of a PR during a push event and the extraction of labels from the PR's commit messages.

import os

import uvicorn
from fastapi import FastAPI
from github import Auth, Github

from fastgithub import GithubWebhookHandler, SignatureVerificationSHA256, webhook_router
from fastgithub.recipes.github import AutoCreatePullRequest, LabelsFromCommits

signature_verification = SignatureVerificationSHA256(secret="mysecret")  # noqa: S106
webhook_handler = GithubWebhookHandler(signature_verification)

github = Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"]))

webhook_handler.listen("push", [AutoCreatePullRequest(github)])
webhook_handler.listen("pull_request", [LabelsFromCommits(github)])


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

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

You can define your own Recipe (or GithubRecipe) by inherit from these classes. A Recipe need a class attribute events that take a list of events to listen to, by default the recipe is listen by any type of event (ie. *).

The webhook_router uses the __call__ method to perform the hooks.

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"])
        if not gh.rate_status.too_low():
            print(f"Hello from {gh.repo.full_name}!")

⛏️ 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

Acknowledgements

Initial ideas and designs were inspired by python-github-webhook and python-github-bot-api