Skip to content

Commit 8b4e228

Browse files
westoverclaude
westover
and
claude
committed
feat: initial GitHub webhook receiver implementation
- FastAPI service for receiving GitHub webhooks - HMAC-SHA256 signature verification - Event handlers for push, PR, issues, comments, workflows, deployments - Structured logging with context - Health check endpoint - PDM dependency management - Pytest test suite - Systemd service configuration - GitHub Actions deployment workflow Multi-repo coordination foundation - handlers are stubs for now. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
0 parents  commit 8b4e228

10 files changed

Lines changed: 1346 additions & 0 deletions

File tree

‎.env.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# GitHub Webhook Receiver Configuration
2+
3+
# Application
4+
APP_ENV=production
5+
APP_PORT=9000
6+
APP_HOST=0.0.0.0
7+
8+
# GitHub Webhook Secret (from GitHub App)
9+
GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
10+
11+
# Logging
12+
LOG_LEVEL=INFO
13+
LOG_FORMAT=json

‎.github/workflows/deploy.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Deploy Webhook Receiver
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
jobs:
10+
deploy:
11+
runs-on: [self-hosted, app-server]
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Install dependencies
18+
run: pdm install --prod
19+
20+
- name: Run tests
21+
run: pdm run pytest
22+
23+
- name: Deploy service
24+
run: |
25+
sudo systemctl restart github-webhook-receiver
26+
sleep 2
27+
curl -f http://localhost:9000/health || exit 1
28+
29+
- name: Deployment successful
30+
run: echo "✅ Webhook receiver deployed successfully"

‎.gitignore‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
MANIFEST
23+
24+
# PDM
25+
.pdm.toml
26+
.pdm-python
27+
__pypackages__/
28+
29+
# Virtual environments
30+
.venv/
31+
venv/
32+
ENV/
33+
env/
34+
35+
# Environment variables
36+
.env
37+
.env.local
38+
39+
# IDE
40+
.vscode/
41+
.idea/
42+
*.swp
43+
*.swo
44+
*~
45+
46+
# Testing
47+
.pytest_cache/
48+
.coverage
49+
htmlcov/
50+
.tox/
51+
52+
# Logs
53+
*.log
54+
55+
# OS
56+
.DS_Store
57+
Thumbs.db

‎README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# GitHub Webhook Receiver
2+
3+
Multi-repo coordination and automation webhook receiver for the neherdata organization.
4+
5+
## Overview
6+
7+
Receives GitHub webhooks from the `Neherdata-deploy-bot` GitHub App to enable:
8+
- Multi-repo deployment coordination
9+
- Claude automation triggers
10+
- Cross-repo workflow orchestration
11+
- Centralized event logging and monitoring
12+
13+
## Features
14+
15+
- **Webhook Verification**: HMAC-SHA256 signature verification
16+
- **Event Processing**: Handles push, PR, issues, comments, workflows, deployments
17+
- **Structured Logging**: JSON logs with context for debugging
18+
- **Health Monitoring**: Health check endpoint for monitoring
19+
- **Extensible**: Easy to add new event handlers
20+
21+
## Setup
22+
23+
### Prerequisites
24+
25+
- Python 3.11+
26+
- PDM (Python Dependency Manager)
27+
- Cloudflare tunnel configured
28+
29+
### Installation
30+
31+
```bash
32+
# Clone repository
33+
git clone https://github.com/neherdata/github-webhook-receiver.git
34+
cd github-webhook-receiver
35+
36+
# Install dependencies
37+
pdm install --prod
38+
39+
# Configure environment
40+
cp .env.example .env
41+
# Edit .env with your configuration
42+
```
43+
44+
### Configuration
45+
46+
```bash
47+
# .env
48+
GITHUB_WEBHOOK_SECRET=your-webhook-secret-from-github-app
49+
APP_PORT=9000
50+
APP_HOST=0.0.0.0
51+
LOG_LEVEL=INFO
52+
```
53+
54+
### Running
55+
56+
```bash
57+
# Development
58+
pdm run uvicorn app.main:app --reload --port 9000
59+
60+
# Production (via systemd)
61+
sudo systemctl start github-webhook-receiver
62+
```
63+
64+
## Deployment
65+
66+
Deployed to westoverxyz via Ansible:
67+
68+
```bash
69+
cd /path/to/nds_server/ansible
70+
ansible-playbook playbooks/deploy-webhook-receiver.yml
71+
```
72+
73+
Service runs on port 9000, exposed via Cloudflare tunnel at:
74+
- `https://github-webhooks.westover.services/webhooks/github`
75+
- `https://github-callback.westover.services` (OAuth callbacks)
76+
77+
## Event Handlers
78+
79+
### Implemented
80+
81+
- ✅ **push**: Deployment coordination (TODO: implement logic)
82+
- ✅ **pull_request**: PR coordination (TODO: implement logic)
83+
- ✅ **issues**: Claude automation trigger (TODO: implement logic)
84+
- ✅ **issue_comment**: Comment-triggered actions (TODO: implement logic)
85+
- ✅ **workflow_run**: Workflow monitoring (TODO: implement logic)
86+
- ✅ **deployment**: Deployment tracking (TODO: implement logic)
87+
88+
### Planned
89+
90+
- Cross-repo dependency updates
91+
- Automated changelog generation
92+
- Deployment status aggregation
93+
- Claude task coordination
94+
95+
## Testing
96+
97+
```bash
98+
# Run tests
99+
pdm run pytest
100+
101+
# Test webhook locally
102+
curl -X POST http://localhost:9000/webhooks/github \
103+
-H "X-Hub-Signature-256: sha256=..." \
104+
-H "X-GitHub-Event: ping" \
105+
-H "X-GitHub-Delivery: abc123" \
106+
-d '{"zen": "testing"}'
107+
```
108+
109+
## Security
110+
111+
- Webhook signatures verified using HMAC-SHA256
112+
- Secret stored in environment variables (not in code)
113+
- Rate limiting via Cloudflare
114+
- Systemd service runs as non-root user
115+
116+
## Monitoring
117+
118+
- Health endpoint: `/health`
119+
- Structured logs: `sudo journalctl -u github-webhook-receiver -f`
120+
- Cloudflare Analytics dashboard
121+
122+
## Architecture
123+
124+
```
125+
GitHub Event → GitHub App → Cloudflare Tunnel → FastAPI Receiver
126+
↓
127+
Event Handlers
128+
↓
129+
[Coordination Logic]
130+
↓
131+
Trigger Actions (deployments, etc.)
132+
```
133+
134+
## License
135+
136+
MIT

‎app/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""GitHub Webhook Receiver"""
2+
3+
__version__ = "1.0.0"

0 commit comments

Comments
 (0)