# 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