Contributing

git clone https://github.com/myk-org/github-webhook-server.git
cd github-webhook-server

# Install all dependencies including dev and test groups
uv sync

# Activate virtual environment
source .venv/bin/activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e ".[tests]"

# Set data directory
export WEBHOOK_SERVER_DATA_DIR=./webhook_server_data

# Create minimal config.yaml
mkdir -p webhook_server_data
cat > webhook_server_data/config.yaml << 'EOF'
github-app-id: 123456
webhook-ip: https://smee.io/your-channel
github-tokens:
  - ghp_your_github_token

repositories:
  test-repo:
    name: your-org/test-repository
    protected-branches:
      main: []
EOF

# Run server
uv run entrypoint.py

uv run ruff format

uv run ruff format --check

uv run ruff check

uv run ruff check --fix

# pyproject.toml
[tool.ruff]
line-length = 120
fix = true

[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "PLC0415", "ARG", "RUF059"]

uv run mypy webhook_server/

# pyproject.toml
[tool.mypy]
check_untyped_defs = true
disallow_any_generics = true
disallow_incomplete_defs = true
disallow_untyped_defs = true
no_implicit_optional = true
show_error_codes = true
warn_unused_ignores = true
strict_equality = true
extra_checks = true

# ✅ CORRECT - Complete type hints
async def process_webhook(pr: PullRequest, reviewers: list[str]) -> None:
    ...

# ❌ WRONG - Missing type hints
async def process_webhook(pr, reviewers):
    ...

uv run ruff check && uv run ruff format && uv run mypy webhook_server/

# Run all tests with coverage report
uv run --group tests pytest -n auto --cov=webhook_server

# Generate HTML coverage report
uv run --group tests pytest -n auto --cov=webhook_server --cov-report=html

# Open coverage report
open .tests_coverage/index.html

# pyproject.toml
[tool.coverage.run]
omit = ["webhook_server/tests/*"]

[tool.coverage.report]
fail_under = 90
skip_empty = true

uv run --group tests pytest -n auto

uv run --group tests pytest webhook_server/tests/test_pull_request_handler.py -v

uv run --group tests pytest webhook_server/tests/test_config.py::TestConfig::test_valid_config -v

# Run only integration tests
uv run --group tests pytest -m integration

# Skip slow tests
uv run --group tests pytest -m "not slow"

webhook_server/tests/
├── test_*.py              # Unit and integration tests
├── manifests/             # Test configuration files
│   └── config.yaml
├── e2e/                   # End-to-end tests
│   └── test_pull_request_flow.py
└── conftest.py            # Shared fixtures

import pytest
from unittest.mock import AsyncMock, Mock, patch
from webhook_server.libs.handlers.pull_request_handler import PullRequestHandler

class TestPullRequestHandler:
    @pytest.fixture
    def mock_github_webhook(self):
        """Create mock GithubWebhook instance."""
        mock = Mock()
        mock.repository_data = {
            "collaborators": {"edges": []},
            "labels": {"nodes": []}
        }
        mock.unified_api = AsyncMock()
        return mock

    @pytest.mark.asyncio
    async def test_process_pull_request(self, mock_github_webhook):
        """Test pull request processing."""
        handler = PullRequestHandler(mock_github_webhook)
        event_data = {
            "action": "opened",
            "pull_request": {
                "number": 123,
                "title": "Test PR"
            }
        }
        
        await handler.process_event(event_data)
        
        # Verify API calls
        mock_github_webhook.unified_api.add_pr_labels.assert_called_once()

pip install pre-commit

# Install git hooks
pre-commit install

pre-commit run --all-files

pre-commit run ruff --all-files
pre-commit run mypy --all-files

pre-commit autoupdate

type: description

Optional body explaining the change

Optional footer (breaking changes, issues)

feat: add support for custom PR size labels

fix: resolve WebSocket connection timeout issue

docs: update configuration examples

refactor: optimize repository data fetching

test: add tests for label handler

webhook_server/
├── app.py                    # FastAPI application
├── libs/
│   ├── config.py            # Configuration management
│   ├── github_api.py        # GitHub API wrapper
│   ├── handlers/            # Event handlers
│   │   ├── pull_request_handler.py
│   │   ├── issue_comment_handler.py
│   │   └── ...
│   └── exceptions.py        # Custom exceptions
├── utils/
│   ├── helpers.py           # Utility functions
│   ├── context.py           # Structured logging context
│   └── constants.py         # Constants
├── web/
│   └── log_viewer.py        # Log viewer web interface
└── tests/
    ├── test_*.py            # Tests
    └── manifests/           # Test data

from webhook_server.libs.github_api import GithubWebhook
from webhook_server.utils.helpers import get_logger_with_params

class MyHandler:
    def __init__(self, github_webhook: GithubWebhook) -> None:
        self.github_webhook = github_webhook
        self.logger = get_logger_with_params(
            name="MyHandler",
            repository=github_webhook.repository,
            hook_id=github_webhook.hook_id
        )

    async def process_event(self, event_data: dict) -> None:
        """Process webhook event."""
        self.logger.info(f"Processing event: {event_data['action']}")
        
        # Use unified API for GitHub operations
        await self.github_webhook.unified_api.some_operation()

import asyncio
from github.PullRequest import PullRequest

# ✅ CORRECT - Wrap PyGithub calls
await asyncio.to_thread(pull_request.create_issue_comment, "Comment")
is_draft = await asyncio.to_thread(lambda: pull_request.draft)

# ❌ WRONG - Direct call blocks event loop
pull_request.create_issue_comment("Comment")  # BLOCKS!

from typing import Any
from github.PullRequest import PullRequest

# ✅ CORRECT
async def assign_reviewers(
    self,
    pull_request: PullRequest,
    reviewers: list[str]
) -> None:
    ...

# ❌ WRONG - Missing type hints
async def assign_reviewers(self, pull_request, reviewers):
    ...

from webhook_server.utils.helpers import get_logger_with_params
from webhook_server.utils.context import get_context

# Create logger with context
logger = get_logger_with_params(
    name="ComponentName",
    repository="org/repo",
    hook_id="delivery-id"
)

# Log messages
logger.debug("Detailed technical information")
logger.info("General information")
logger.warning("Warning that needs attention")
logger.error("Error requiring investigation")

# Use logger.exception for errors with traceback
try:
    await some_operation()
except Exception:
    logger.exception("Operation failed")  # Includes traceback

from webhook_server.libs.exceptions import RepositoryNotFoundInConfigError

# ✅ CORRECT - Specific exceptions
try:
    config.get_repository("org/repo")
except RepositoryNotFoundInConfigError:
    logger.error("Repository not in config")
    return

# ✅ CORRECT - Use logger.exception for unexpected errors
except Exception:
    logger.exception("Unexpected error processing webhook")
    raise

def process_webhook(
    hook_id: str,
    event_type: str,
    payload: dict[str, Any]
) -> None:
    """Process incoming GitHub webhook.

    Args:
        hook_id: GitHub delivery ID for tracking
        event_type: GitHub event type (pull_request, push, etc.)
        payload: Webhook payload data

    Raises:
        RepositoryNotFoundInConfigError: If repository not in config
        ValueError: If payload is invalid

    Example:
        >>> process_webhook("abc-123", "pull_request", {...})
    """
    ...