195 lines
4.4 KiB
Markdown
195 lines
4.4 KiB
Markdown
# 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 |