gitwebhooks 2.1.0__py3-none-any.whl

gitwebhooks-2.1.0.dist-info/METADATA

@@ -0,0 +1,494 @@
+Metadata-Version: 2.4
+Name: gitwebhooks
+Version: 2.1.0
+Summary: A lightweight Git webhook server for automated deployment supporting GitHub, Gitee, GitLab, and custom webhooks
+Author-email: Troy Tse <troy@holyhi.net>
+Maintainer-email: Troy Tse <troy@holyhi.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/troytse/git-webhooks-server
+Project-URL: Documentation, https://github.com/troytse/git-webhooks-server#readme
+Project-URL: Repository, https://github.com/troytse/git-webhooks-server.git
+Project-URL: Issues, https://github.com/troytse/git-webhooks-server/issues
+Keywords: webhook,git,github,gitee,gitlab,deployment,automation,server,devops
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Dynamic: license-file
+
+# Simple Git Webhooks Server
+
+[README](README.md) | [中文说明](README.zh.md)
+
+## Table of Contents
+- [Introduction](#introduction)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Uninstallation](#uninstallation)
+- [Usage](#usage)
+  - [Github](#github)
+  - [Gitee](#gitee)
+  - [Gitlab](#gitlab)
+  - [Custom](#custom)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+
+## Introduction
+
+A lightweight Git webhook server for automated deployment.
+
+- Implemented with Python 3.6+ (standard library only)
+- Supports Github, Gitee, Gitlab, and custom repositories
+- Custom working directory and command for different repositories
+- Installable as a Systemd service
+- Modular architecture for easy extension and testing
+
+## Architecture
+
+**Version 2.0** features a modular package structure:
+
+```
+gitwebhooks/
+├── models/          # Data models (Provider, Request, Result)
+├── config/          # Configuration management
+├── auth/            # Signature verification
+├── handlers/        # Webhook handlers
+├── utils/           # Utilities
+└── logging/         # Logging setup
+```
+
+**Key Features:**
+- **Dependency Injection**: ConfigurationRegistry, VerifierFactory, HandlerFactory
+- **Abstract Base Classes**: SignatureVerifier, WebhookHandler
+- **No External Dependencies**: 100% Python standard library
+- **In-Place Execution**: CLI runs from source directory
+
+## Installation
+
+### Prerequisites
+
+- Python 3.6 or higher
+- pip (Python package manager)
+- sudo/root access (for systemd service installation)
+
+### Recommended: pipx (System-wide installation)
+
+pipx is the recommended way to install git-webhooks-server system-wide.
+
+```bash
+# Install pipx (if not already installed)
+sudo apt install pipx  # Ubuntu/Debian
+# or: python3 -m pip install --user pipx
+
+# Install git-webhooks-server
+pipx install git-webhooks-server
+```
+
+**Why pipx?**
+- Isolated from system Python packages
+- No dependency conflicts
+- Easy to upgrade and uninstall
+- Automatic service file configuration
+
+### Alternative: venv (Virtual environment)
+
+If you prefer using Python's built-in venv module:
+
+```bash
+# Create virtual environment
+python3 -m venv ~/venv/gitwebhooks
+
+# Activate and install
+source ~/venv/gitwebhooks/bin/activate
+pip install git-webhooks-server
+
+# Add to PATH (optional)
+echo 'export PATH="$HOME/venv/gitwebhooks/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### ⚠️ NOT Recommended: System pip
+
+**Warning**: Installing directly with `sudo pip install` is NOT recommended:
+
+```bash
+# DO NOT DO THIS
+sudo pip install git-webhooks-server
+```
+
+**Risks**:
+- Can conflict with system Python packages
+- May break system tools that depend on Python
+- Difficult to uninstall cleanly
+
+### Initialize Configuration
+
+```bash
+# Interactive configuration setup (prompts for configuration level)
+gitwebhooks-cli config init
+
+# Or specify configuration level directly
+gitwebhooks-cli config init user      # User level (~/.gitwebhooks.ini)
+gitwebhooks-cli config init local      # Local level (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli config init system # System level (/etc/gitwebhooks.ini, requires root)
+```
+
+The wizard will prompt for:
+1. Configuration level (system/local/user)
+2. Server configuration (address, port, log file)
+3. Git platform (github/gitee/gitlab/custom)
+4. Platform-specific settings (webhook events, verification, secret)
+5. Repository configuration (name, working directory, deploy command)
+
+This will create a configuration file with secure permissions (0600).
+
+### Install as systemd Service
+
+The service installation command automatically detects your installation type (pipx, venv, or system) and generates the appropriate service file.
+
+```bash
+# Install and start as a systemd service
+sudo gitwebhooks-cli service install
+
+# Preview service file without installing (dry-run mode)
+sudo gitwebhooks-cli service install --dry-run
+
+# Install with verbose output
+sudo gitwebhooks-cli service install --verbose
+sudo gitwebhooks-cli service install -v      # Basic verbosity
+sudo gitwebhooks-cli service install -vv     # Extra verbosity
+
+# Force overwrite existing service
+sudo gitwebhooks-cli service install --force
+
+# Uninstall the service
+sudo gitwebhooks-cli service uninstall
+```
+
+**Service file auto-detection**:
+- **pipx installation**: Uses `gitwebhooks-cli` command directly
+- **venv/virtualenv**: Uses `python -m gitwebhooks.cli` with environment's Python
+- **System pip**: Uses system Python with `python -m gitwebhooks.cli`
+- **conda**: Not supported - installation will be refused with clear error message
+
+### Manual Installation
+
+To install manually without pip:
+
+```bash
+# Make CLI executable
+chmod +x gitwebhooks-cli
+
+# Create hard link to system path
+sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
+```
+
+### Verify Installation
+
+```bash
+gitwebhooks-cli --help
+```
+
+## Migrating from System pip Installation
+
+If you previously installed git-webhooks-server using `sudo pip install`,
+follow these steps to migrate to a recommended installation method.
+
+### Step 1: Uninstall the old installation
+
+```bash
+sudo pip uninstall git-webhooks-server
+```
+
+### Step 2: Backup your configuration (if exists)
+
+```bash
+cp ~/.gitwebhook.ini ~/.gitwebhook.ini.backup
+```
+
+### Step 3: Stop and uninstall the service (if installed)
+
+```bash
+sudo systemctl stop git-webhooks-server
+sudo systemctl disable git-webhooks-server
+sudo gitwebhooks-cli service uninstall
+```
+
+### Step 4: Install using the recommended method
+
+Choose **pipx** (recommended):
+```bash
+# Install pipx if needed
+sudo apt install pipx  # Ubuntu/Debian
+# or: python3 -m pip install --user pipx
+
+# Install git-webhooks-server
+pipx install git-webhooks-server
+```
+
+Or **venv**:
+```bash
+# Create virtual environment
+python3 -m venv ~/venv/gitwebhooks
+source ~/venv/gitwebhooks/bin/activate
+
+# Install git-webhooks-server
+pip install git-webhooks-server
+```
+
+### Step 5: Restore configuration (if backed up)
+
+```bash
+# If you backed up your configuration
+cp ~/.gitwebhook.ini.backup ~/.gitwebhook.ini
+# Or create a new one
+gitwebhooks-cli config init
+```
+
+### Step 6: Reinstall the service
+
+```bash
+sudo gitwebhooks-cli service install
+```
+
+### Step 7: Verify
+
+```bash
+sudo systemctl status git-webhooks-server
+```
+
+## Uninstallation
+
+```bash
+# Uninstall systemd service (if installed)
+sudo gitwebhooks-cli service uninstall --purge
+
+# Remove the package
+pip uninstall gitwebhooks
+```
+
+## Usage
+
+### 1. Configure Repository
+
+Edit `~/.gitwebhook.ini`:
+
+```ini
+[your_name/repository]
+cwd=/path/to/your/repository
+cmd=git fetch --all && git reset --hard origin/master && git pull
+```
+
+### 2. Restart Service
+
+```bash
+# If running as a service
+systemctl restart git-webhooks-server
+
+# Or run directly:
+gitwebhooks-cli
+```
+
+### 3. Add Webhook
+
+#### Github
+
+![github](doc/github.png)
+![github-success](doc/github-success.png)
+
+#### Gitee
+
+![gitee](doc/gitee.png)
+![gitee-success](doc/gitee-success.png)
+
+#### Gitlab
+
+![gitlab](doc/gitlab.png)
+![gitlab-success](doc/gitlab-success.png)
+
+#### Custom
+
+For custom webhook sources, configure like this:
+
+```ini
+[custom]
+# Header to identify the source
+header_name=X-Custom-Header
+header_value=Custom-Git-Hookshot
+# Header for token verification
+header_token=X-Custom-Token
+# Path to repository name in JSON payload
+identifier_path=project.path_with_namespace
+verify=True
+secret=123456
+```
+
+The handler accepts POST data with `application/json` or `application/x-www-form-urlencoded` content type. See [Github](https://developer.github.com/webhooks/event-payloads/#example-delivery) / [Gitee](https://gitee.com/help/articles/4186) / [Gitlab](https://gitlab.com/help/user/project/integrations/webhooks#push-events) for payload examples.
+
+Example payload:
+```json
+{
+  "project": {
+    "path_with_namespace": "your_name/repository"
+  }
+}
+```
+
+![custom-header](doc/custom-header.png)
+![custom-body](doc/custom-body.png)
+![custom-response](doc/custom-response.png)
+
+## Configuration
+
+Default configuration file: `~/.gitwebhook.ini`
+
+### Initialize Configuration
+
+```bash
+# Interactive configuration setup
+gitwebhooks-cli config init
+
+# Or specify configuration level directly
+gitwebhooks-cli config init user
+sudo gitwebhooks-cli config init system
+```
+
+### View Configuration
+
+```bash
+# View current configuration file (auto-detects location)
+gitwebhooks-cli config view
+
+# View specific configuration file
+gitwebhooks-cli config view -c /path/to/config.ini
+```
+
+The `config view` command displays:
+- Configuration file path and source (user-specified or auto-detected)
+- Configuration content organized by sections
+- Sensitive fields (containing: secret, password, token, key, passphrase) highlighted in yellow
+
+To disable color highlighting:
+```bash
+NO_COLOR=1 gitwebhooks-cli config view
+```
+
+### Server Configuration
+
+```ini
+[server]
+address=0.0.0.0          # Listen address
+port=6789                # Listen port
+log_file=~/.gitwebhook.log  # Log file (empty = stdout only)
+```
+
+### SSL Configuration (Optional)
+
+```ini
+[ssl]
+enable=False
+key_file=/path/to/key.pem
+cert_file=/path/to/cert.pem
+```
+
+### Provider Configuration
+
+```ini
+[github]
+verify=True              # Enable signature verification
+secret=your_webhook_secret
+handle_events=push,pull_request  # Events to handle (empty = all)
+
+[gitee]
+verify=True
+secret=your_webhook_secret
+
+[gitlab]
+verify=True
+secret=your_webhook_token
+
+[custom]
+header_name=X-Custom-Header
+header_value=Your-Identifier
+header_token=X-Custom-Token
+identifier_path=project.path_with_namespace
+verify=True
+secret=your_secret
+```
+
+### Repository Configuration
+
+```ini
+[owner/repository]
+cwd=/path/to/repo    # Working directory
+cmd=your_command     # Command to execute
+```
+
+## Project Structure
+
+```
+git-webhooks-server/
+├── gitwebhooks/              # Python package (modular v2.0)
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── cli.py                # CLI entry point
+│   ├── server.py             # HTTP server
+│   ├── models/               # Data models
+│   ├── config/               # Configuration management
+│   ├── auth/                 # Signature verification
+│   ├── handlers/             # Webhook handlers
+│   ├── utils/                # Utilities
+│   └── logging/              # Logging setup
+├── gitwebhooks-cli           # CLI wrapper script
+├── install.sh                # Installation script
+├── git-webhooks-server.ini.sample
+└── tests/                    # Test suite
+```
+
+## Development
+
+### Running from Source
+
+```bash
+# Method 1: Use CLI tool (recommended)
+./gitwebhooks-cli -c git-webhooks-server.ini.sample
+
+# Method 2: Use module entry
+python3 -m gitwebhooks.cli -c git-webhooks-server.ini.sample
+```
+
+### Running Tests
+
+```bash
+# Using pytest
+python3 -m pytest tests/
+
+# Or using unittest
+python3 -m unittest discover tests/
+```
+
+## License
+
+MIT License

gitwebhooks-2.1.0.dist-info/RECORD

@@ -0,0 +1,47 @@
+gitwebhooks/__init__.py,sha256=lBuLRzIrUhawp8mQG3IB5HZiksNeUmuuDBRK5_hcZvw,422
+gitwebhooks/__main__.py,sha256=DW1lmngPDSFHJKSyaG2Dd5k3UguGSuYPUM2xKR8DhTo,189
+gitwebhooks/server.py,sha256=keQcfOysoitx7cINcTkaDvhe6nScIFL2K8dCCViFF-o,3986
+gitwebhooks/auth/__init__.py,sha256=Hu88BS6aOickrWBBWM2ppTzy2xOJfWODYkp752bPTPM,532
+gitwebhooks/auth/custom.py,sha256=zDJdQCOCCd1u1D10T7a6rE2KUggBXvgjtTkQPL3Thfc,1216
+gitwebhooks/auth/factory.py,sha256=vvI1epyIGQ4MSgjRrW7Gya98Kc9k8WzjOru_PpMgOB8,2474
+gitwebhooks/auth/gitee.py,sha256=8o_tKugZrW2or-uoRzjCo3h-WRlm3zbYmkTNbf5zL6s,3249
+gitwebhooks/auth/github.py,sha256=sY3xPwfYvD3tID5b26qHhTI1E9EW2VNHaFEygmsZYCg,1619
+gitwebhooks/auth/gitlab.py,sha256=Aoz77VbYRASxNXqOAnK5__9hkGgaf9kLMoCgOnvFMNE,862
+gitwebhooks/auth/verifier.py,sha256=onIvbmFVWpk7vkdEiyF48S4KrtbP48NH3FLz0fE24XE,971
+gitwebhooks/cli/__init__.py,sha256=o81CV1rggR_YqSW80JP_CSKMGBQkQYJqDjsiUtvvW-I,2891
+gitwebhooks/cli/config.py,sha256=rVq7qh2KB9Z4Up2bc9zWDvGpf28iALdnu1pGIJ0p6-8,6373
+gitwebhooks/cli/init_wizard.py,sha256=PfCZfYodoUtHCSX1aLdhXJtSg0YD4oCUcNJaL0tSQVs,21463
+gitwebhooks/cli/prompts.py,sha256=slbAcjEUY83lanuXbfyt7BP4m1ZrgQEcgkjI96hsw60,7167
+gitwebhooks/cli/service.py,sha256=GC3C2WPr4JzyYig3eh4WA4_NdWLfKuxgx7AJrkPJYE4,11057
+gitwebhooks/config/__init__.py,sha256=CnU2ybNi8Yf5YqGWe7uls98ditREEuxuj5mW0t1ti0s,413
+gitwebhooks/config/loader.py,sha256=rrMBunCE1swj-KMDvkTxy-mzG-Lalz-l0Hsw1Xw0rFc,5390
+gitwebhooks/config/models.py,sha256=oZ0ISLxh0zq5U7fqpAk2as7qHsOcbwj257BZEaK1zO8,4758
+gitwebhooks/config/registry.py,sha256=5_rsi9rKkgxiDSnnRmPYCy6AQCEBPxeKgmUC-_4u6h4,3165
+gitwebhooks/config/server.py,sha256=ucFDoLF4QWPqn_-rBRe2uerpxMS6AgM2TLbC89o9zdQ,2739
+gitwebhooks/handlers/__init__.py,sha256=nkGxNoHdrcNtQ2I5TlVNqJovUfmG7vDlagxGLsCKqsk,505
+gitwebhooks/handlers/base.py,sha256=Hd_FScG3E5fe2ZCihFaAghWHGdQLliix1r_Mxeyp1S0,3416
+gitwebhooks/handlers/custom.py,sha256=rGkIdOqrqdW64VTLwbcTS4zOAfcZAL1OdDq5UcsJsEI,2660
+gitwebhooks/handlers/factory.py,sha256=wZHHSVXh_pJvdipkdmtMdzaTsTny7zEGxZqSVlAsr6Q,2570
+gitwebhooks/handlers/gitee.py,sha256=_mXqVXYBRQB1JMWO-QbaBxTD3Efj_ZFYMWa3csfLjgQ,4149
+gitwebhooks/handlers/github.py,sha256=gUMFn4Y47JM8m4ot55_zGaDFOzM03Gz8J9_Ov8aFBjo,1617
+gitwebhooks/handlers/gitlab.py,sha256=UkK3R_KSKSt0s7XAtH1_G_uid85tqiL12qND8_PnosA,1610
+gitwebhooks/handlers/request.py,sha256=uedC-zAehQZzG4YIUdq4TsQYPZ-PoVHkKDJb-FEC27s,8989
+gitwebhooks/logging/__init__.py,sha256=CmL5WD2RgZ76uhrxzwnIfOEd_HgTZMTtTjjqYSY06GA,146
+gitwebhooks/logging/setup.py,sha256=Y9h0WGDudCrdLZ8dm_Xp3zt_Xp7x7WdDio4MK9ZFBCg,1577
+gitwebhooks/main/__init__.py,sha256=U8ls6BZYY-OheBOwMM3wVDQhIgmylcc3M7WRYZ_K4fs,3163
+gitwebhooks/main/__main__.py,sha256=qE-72BSpj15NeV6-oWpMXR3ARmATeSGUO8VUB98sxF8,223
+gitwebhooks/models/__init__.py,sha256=DmZBPoNeh7eB9Ntr6d4T9QY6-LckvrHNGg8FVcpuvP0,273
+gitwebhooks/models/provider.py,sha256=lmjJvGjklD1VTKB6UF9V-gZCPwXhiip8DR8qXs_A-F8,451
+gitwebhooks/models/request.py,sha256=UkdTiBpX4-XipeOnhE0SvAaR53bFFh8EKftSVFjNBLM,1838
+gitwebhooks/models/result.py,sha256=0M3fjeUH3CM4Mjpc9e4ZxBdfPO9xlODRRdlshVomQYQ,1020
+gitwebhooks/utils/__init__.py,sha256=qZcrINToHF8qAtIIDAjOlzfKcohCVyYe2ZaKYsWbOxY,219
+gitwebhooks/utils/constants.py,sha256=V_SFYrHpkX-fKSfVwx8fXwBjZe2f4EjoVz925RZryrs,1729
+gitwebhooks/utils/exceptions.py,sha256=Mfz-FOCiHZiYmpSQDw36S9HarLE2wPLfFbkeHfWJnkk,627
+gitwebhooks/utils/executor.py,sha256=-zQUV5t-eq0JF6T4EvsUlvg4lnBtahRGrV8N3iVgx_c,923
+gitwebhooks/utils/systemd.py,sha256=eseaVdsxBofZf7yQPCOP-CbmZapRJtrS0vnBGERdL0s,7925
+gitwebhooks-2.1.0.dist-info/licenses/LICENSE,sha256=NV5F0xpN-DVJuhc0qzOsXtLjf3l8X18zehW_7F4qI50,1083
+gitwebhooks-2.1.0.dist-info/METADATA,sha256=ZMiNBDT_VYs19b3sjbREyiiSTDw1fl5xuOy0yTlwCeI,12854
+gitwebhooks-2.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gitwebhooks-2.1.0.dist-info/entry_points.txt,sha256=AVgLU9oFCt0XW_GbziMiGoHREewpn6JJQ_FTYX7jsGc,57
+gitwebhooks-2.1.0.dist-info/top_level.txt,sha256=9a6CxnHxBD53HL38GUeZETIvnUhUKcgDRIGJkCqwc3o,12
+gitwebhooks-2.1.0.dist-info/RECORD,,

gitwebhooks-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitwebhooks-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitwebhooks-cli = gitwebhooks.cli:main

gitwebhooks-2.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Troy Tse <troy@holyhi.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitwebhooks-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitwebhooks