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

# 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

# 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:

{
  "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:

{
  "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:

{
  "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

# 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