README.md

@@ -0,0 +1,195 @@
+# Gitea Event Bridge Service
+
+A Flask-based webhook event bridge service that receives Gitea webhooks, routes them based on trigger conditions, and broadcasts events via Server-Sent Events (SSE).
+
+## Features
+
+- **Webhook Reception**: Accept Gitea webhooks via POST endpoint
+- **Event Routing**: Automatically detect and route events based on:
+  - Labels (`start-pipeline`, `needs-decision`)
+  - Comment commands (`/pipeline start`)
+  - PR events (opened, synchronized)
+- **SSE Broadcasting**: Real-time event streaming to connected clients
+- **Activity Logging**: JSON Lines format for audit trail
+- **Webhook Verification**: HMAC signature validation (optional)
+
+## Supported Gitea Event Types
+
+- `issue` (opened, closed, reopened, edited)
+- `issue.label` (added, removed)
+- `pull_request` (opened, closed, reopened, synchronize, edited)
+- `pull_request.label` (added, removed)
+- `pull_request.review` (approved, rejected, commented)
+- `comment` (created, edited, deleted)
+- `repository` (created, deleted, archived)
+- `organization` (member_added, member_removed)
+
+## Quick Start
+
+### Using Docker Compose
+
+```bash
+# Clone and navigate to the directory
+cd gitea-event-bridge
+
+# Copy environment file
+cp .env.example .env
+
+# Edit .env with your configuration
+# Set GITEA_WEBHOOK_SECRET if using signature verification
+
+# Start the service
+docker-compose up -d
+
+# Check health
+curl http://localhost:5000/health
+```
+
+### Manual Setup
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy and configure environment
+cp .env.example .env
+
+# Run the application
+python app.py
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `HOST` | `0.0.0.0` | Server bind address |
+| `PORT` | `5000` | Server port |
+| `DEBUG` | `false` | Enable debug mode |
+| `OPENCODE_URL` | `http://localhost:8080` | OpenCode server URL |
+| `LOG_FILE` | `activity.json` | Activity log file path |
+| `GITEA_WEBHOOK_SECRET` | (empty) | Secret for signature verification |
+| `AUTO_TRIGGER_PIPELINE` | `true` | Enable automatic pipeline triggers |
+| `AUTO_TRIGGER_REVIEW` | `true` | Enable automatic review triggers |
+
+## API Endpoints
+
+### POST /webhook/gitea
+
+Receive Gitea webhooks.
+
+**Headers:**
+- `X-Gitea-Event`: Event type
+- `X-Gitea-Signature`: HMAC signature (if secret configured)
+
+**Response:**
+```json
+{
+  "success": true,
+  "event_type": "pull_request",
+  "action": "opened",
+  "repository": "owner/repo",
+  "sender": "username",
+  "triggers": [
+    {
+      "type": "review",
+      "agent": "lead",
+      "trigger": "trigger_lead_review",
+      "reason": "pr:opened"
+    }
+  ]
+}
+```
+
+### GET /events
+
+SSE stream endpoint for real-time events.
+
+**Response:**
+```
+event: gitea_event
+data: {"event_type": "pull_request", "action": "opened", ...}
+```
+
+### GET /health
+
+Health check endpoint.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "sse_connected_clients": 0
+}
+```
+
+### GET /activity
+
+Get recent activity log entries.
+
+**Query Parameters:**
+- `limit`: Maximum entries to return (default: 50, max: 200)
+
+**Response:**
+```json
+{
+  "count": 2,
+  "activities": [
+    {
+      "id": "uuid",
+      "timestamp": "2026-04-08T12:00:00Z",
+      "event_type": "pull_request",
+      "action": "opened",
+      "repository": "owner/repo",
+      "sender": "username",
+      "payload": {...},
+      "routed_to": ["lead"]
+    }
+  ]
+}
+```
+
+## Trigger Conditions
+
+### Label Triggers
+- `start-pipeline` label → Trigger master pipeline
+- `needs-decision` label → Trigger master decision
+
+### Comment Commands
+- `/pipeline start` → Trigger pipeline
+- `/pipeline` → Trigger pipeline (shorthand)
+
+### PR Events
+- PR opened → Trigger lead review
+- PR synchronize → Trigger lead review
+
+## Gitea Webhook Setup
+
+1. In Gitea, go to Repository Settings → Webhooks
+2. Add new webhook:
+   - **URL**: `http://<your-server>/webhook/gitea`
+   - **Secret**: Set to match `GITEA_WEBHOOK_SECRET` (optional)
+   - **Events**: Select events to send
+3. Test the webhook
+
+## Example curl Commands
+
+```bash
+# Test health endpoint
+curl http://localhost:5000/health
+
+# Test SSE stream
+curl -N http://localhost:5000/events
+
+# Get activity log
+curl http://localhost:5000/activity?limit=10
+
+# Simulate webhook (if no secret configured)
+curl -X POST http://localhost:5000/webhook/gitea \
+  -H "Content-Type: application/json" \
+  -H "X-Gitea-Event: pull_request" \
+  -d '{"action": "opened", "repository": {"full_name": "owner/repo"}, "sender": {"login": "user"}, "pull_request": {"number": 1}}'
+```
+
+## License
+
+MIT