{"id":22957501,"url":"https://github.com/tca166/gitwebhook","last_synced_at":"2026-02-16T06:34:19.962Z","repository":{"id":233871400,"uuid":"735028702","full_name":"TCA166/gitWebhook","owner":"TCA166","description":"Flask blueprints for receiving git webhook requests, automatic deployment and testing","archived":false,"fork":false,"pushed_at":"2024-05-12T14:18:21.000Z","size":88,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-08T15:46:24.878Z","etag":null,"topics":["automation","deployment","flask","flask-blueprints","git-webhook","gitea-webhooks","github-webhooks","gitlab-webhooks","pypi-package","python3","testing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/gitAppWebhook/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TCA166.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-23T12:10:28.000Z","updated_at":"2024-12-20T16:42:58.000Z","dependencies_parsed_at":"2024-04-17T14:59:53.541Z","dependency_job_id":"b1ec2161-0218-4462-96b7-cf8f74aa8fa9","html_url":"https://github.com/TCA166/gitWebhook","commit_stats":null,"previous_names":["tca166/gitwebhook"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/TCA166/gitWebhook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TCA166%2FgitWebhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TCA166%2FgitWebhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TCA166%2FgitWebhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TCA166%2FgitWebhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TCA166","download_url":"https://codeload.github.com/TCA166/gitWebhook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TCA166%2FgitWebhook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29501917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T05:57:17.024Z","status":"ssl_error","status_checked_at":"2026-02-16T05:56:49.929Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","deployment","flask","flask-blueprints","git-webhook","gitea-webhooks","github-webhooks","gitlab-webhooks","pypi-package","python3","testing"],"created_at":"2024-12-14T17:17:27.625Z","updated_at":"2026-02-16T06:34:19.940Z","avatar_url":"https://github.com/TCA166.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitWebhook\n\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/gitAppWebhook)](https://pypi.org/project/gitAppWebhook/)\n[![GitHub Pages Documentation](https://img.shields.io/badge/GitHub_Pages-Documentation-blue)](https://tca166.github.io/gitWebhook/)\n\nA Python library providing [Flask blueprints](https://flask.palletsprojects.com/en/3.0.x/blueprints/) for receiving GitHub, GitLab or Gitea webhooks and acting upon them.\nThe library provides webhooks allowing for automatic deployment, testing and integrations.\nHowever due to the open ended nature of the blueprint this behavior can be easily customized thanks to the very open ended class dependency tree.\n\n## Setup\n\n1. Setup the webhook on the git side\n   During the setup be sure to pay close attention to any opportunities to input any sort of secret key.\n   You will need that key later if you want to enable webhook verification **THIS IS SOMETHING THAT I GREATLY ADVISE YOU DO**.\n   For GitHub that would be the secret string that you provide [during creation](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks#creating-a-repository-webhook), for GitLab that would be the [secret token](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#validate-payloads-by-using-a-secret-token) and for Gitea that would be the [authorization token](https://docs.gitea.com/usage/webhooks#authorization-header).\n2. Install this package\n    - Using pip\n\n        ```sh\n        pip install gitAppWebhook\n        ```\n\n    - By cloning the repository\n\n        ```sh\n        git clone https://github.com/TCA166/gitWebhook.git\n        pip install -r gitWebhook/requirements.txt\n        ```\n\n    - By including this repo as a submodule\n\n        ```sh\n        git submodule add https://github.com/example/repo.git gitWebhook\n        pip install -r gitWebhook/requirements.txt\n        ```\n\n    While installing the pip package functions as any other package the thing with this repo folder is that it functions like a local package.\n    That means that cloning this repo into your project folder will allow you to import ```gitWebhook``` as if it was installed via pip.\n    Same applies with adding as submodule with the added benefit of git understanding what is going on better,\n\n3. Create an instance of ```webhookBlueprint``` (or either of it's subclasses) with your settings\n\n    ```python3\n    import gitWebhook\n\n    wb = gitWebhook.webhookBlueprint(token, url_prefix=\"/\")\n    ```\n\n4. Register the instance within a Flask app of your choice\n\n    ```python3\n    from flask import Flask\n\n    app = Flask(__name__)\n    app.register_blueprint(wb)\n    ```\n\nIf you are lost you can always look at official GitHub resources, or look at [wsgi.py](./wsgi.py) where an example configured Flask webapp is located.\n\n## Blueprint classes\n\nThis library provides a basic blueprint derived class for only receiving webhooks and a few derived classes with different webhook processing capabilities.\n\n### webhookBlueprint\n\nThis very basic class itself has no webhook processing capabilities, but functions as a base from which webhook receiving blueprints may be derived from.\nIt fully implements all the verification required for GitHub and GitLab blueprints and as such should be the class you should derive from.\n\n#### webhookBlueprint behavior\n\n1. Verifies the request's validity (Optional but very recommended)\n2. Returns 200\n\n### pullerWebhookBlueprint\n\nThis class derived from ```webhookBlueprint``` is aimed to be used as a means of automating deployment and testing on servers.\nIf you don't want to use GitHub actions, you can always use a Flask app with this blueprint registered.\n\n#### pullerWebhookBlueprint behavior\n\nUpon receiving a ```POST``` request to the / endpoint the blueprint:\n\n1. Verifies the request's validity (Optional but very recommended)\n2. Performs a ```git pull```\n3. Runs a test suite (Optional)\n    1. If the tests failed it tries to revert the pull\n4. Returns to GitHub or GitLab the results of the pull and tests if they have been performed\n\n### functionWebhookBlueprint\n\nThis class derived from ```webhookBlueprint``` is aimed to be used as a means of integrating different services.\nYou provide it on initialization with a list of ```Callable``` taking in webhook payloads as a single argument, and these functions will be called upon receiving a webhook.\nThus you can easily integrate services with this class by simply having integration happen in such a ```Callable```.\n\n#### functionWebhookBlueprint behavior\n\nUpon receiving a ```POST``` request to the / endpoint the blueprint:\n\n1. Verifies the request's validity (Optional but very recommended)\n2. Calls all functions contained within it's ```functions``` list\n3. If any returned False it returns a failure to origin.\n\n### Customization\n\nYou can easily tweak any of the classes to your liking in two ways.\n\n1. Some settings can be tweaked during blueprint instance creation.\n    You can:\n    - enable or disable webhook verification by providing (or not providing) a ```webhookToken```\n    - enable unit test running by providing a ```unittest.testSuite``` instance (pullerWebhookBlueprint)\n    - enable logging by providing a ```logging.Logger``` instance\n    - change blueprint name to avoid conflicts during blueprint registration\n    - limit the blueprints to accept webhooks only from one git app or multiple\n    - limit the blueprints to accept incoming webhooks only from whitelisted IPs\n    - change the command used to invoke git (pullerWebhookBlueprint)\n    - change the OS environment used by child git processes (pullerWebhookBlueprint)\n2. More advanced changes require creating a subclass from webhookBlueprint\n    This isn't that daunting.\n    There are two methods in the class: ```receiveWebhook``` and ```processWebhook```.\n    Override the former to change how the raw request is handled and verified.\n    Override the latter to change what is done once the webhook is verified.\n\n## License\n\nThis work is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftca166%2Fgitwebhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftca166%2Fgitwebhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftca166%2Fgitwebhook/lists"}