freeleaps-ops/apps/gitea-webhook-ambassador-python/USAGE.md

# 🚀 Gitea Webhook Ambassador Usage Guide

## 📋 Table of Contents
1. [Quick Start](#quick-start)
2. [Configuration](#configuration)
3. [API Endpoints](#api-endpoints)
4. [Database Management](#database-management)
5. [Monitoring and Logs](#monitoring-and-logs)
6. [Troubleshooting](#troubleshooting)

## 🚀 Quick Start

### 1. Environment Preparation

```bash
# Clone the project
git clone https://your.repo.url/gitea-webhook-ambassador-python.git
cd gitea-webhook-ambassador-python

# Run quick setup script
./devbox install
```

### 2. Configure Environment

Edit the `.env` file to set required parameters:

```bash
# Edit configuration file
cp .env.example .env
vim .env
```

**Required configuration:**

```bash
# Jenkins configuration
JENKINS_USERNAME=your_jenkins_username
JENKINS_TOKEN=your_jenkins_token

# Security configuration
SECURITY_SECRET_KEY=your_secret_key
```

### 3. Start Service

```bash
# Method 1: Use the startup script
./devbox start

# Method 2: Manual startup
# Start Redis
docker run -d -p 6379:6379 redis:alpine

# Activate virtual environment
source venv/bin/activate

# Start API service
python -m uvicorn app.main_enhanced:app --host 0.0.0.0 --port 8000

# Start Celery worker in a new terminal
celery -A app.tasks.jenkins_tasks worker --loglevel=info

# Start scheduled tasks in a new terminal
celery -A app.tasks.jenkins_tasks beat --loglevel=info
```

### 4. Verify Installation

Visit the following addresses to verify the service:
- **API Docs**: http://localhost:8000/docs
- **Health Check**: http://localhost:8000/health
- **Metrics**: http://localhost:8000/metrics

## ⚙️ Configuration

### Environment Dispatch Configuration

Edit the `config/environments.yaml` file:

```yaml
environments:
  dev:
    branches: ["dev", "develop", "development", "feature/*"]
    jenkins_job: "alpha-build"
    jenkins_url: "https://jenkins-alpha.freeleaps.com"
    priority: 2
  prod:
    branches: ["prod", "production", "main", "master", "release/*"]
    jenkins_job: "production-build"
    jenkins_url: "https://jenkins-prod.freeleaps.com"
    priority: 1
  staging:
    branches: ["staging", "stage", "pre-prod"]
    jenkins_job: "staging-build"
    jenkins_url: "https://jenkins-staging.freeleaps.com"
    priority: 3
  default:
    branches: ["*"]
    jenkins_job: "default-build"
    jenkins_url: "https://jenkins-default.freeleaps.com"
    priority: 4
```

### Deduplication Configuration

```yaml
deduplication:
  enabled: true
  window_seconds: 300  # 5-minute deduplication window
  strategy: "commit_branch"
  cache_ttl: 3600  # Cache for 1 hour
```

## 🔧 API Endpoints

### Webhook Endpoint

Receive Gitea webhook events:

```http
POST /webhook/gitea
```

### Health Check

```http
GET /health
GET /health/queue
GET /health/jenkins
```

Example response:

```json
{
  "status": "healthy",
  "service": "Gitea Webhook Ambassador",
  "version": "1.0.0",
  "timestamp": "2023-01-01T00:00:00Z",
  "jenkins": {"status": "connected"},
  "worker_pool": {"active_workers": 2, "queue_size": 0, "total_processed": 10, "total_failed": 1},
  "database": {"status": "connected"}
}
```

### Queue Status

```http
GET /admin/queue/status
```

Example response:

```json
{
  "active_tasks": 1,
  "queued_tasks": 2,
  "worker_count": 2,
  "queue_length": 3
}
```

### Monitoring Metrics

Returns Prometheus-formatted monitoring metrics.

## 🗄️ Database Management

### Create Project Mapping

Use a Python script to create a project mapping:

```python
from app.services.database_service import get_database_service
import asyncio

db_service = get_database_service()
mapping_data = {
    "repository_name": "freeleaps/test-project",
    "default_job": "test-project-build",
    "branch_jobs": [
        {"branch_name": "dev", "job_name": "test-project-dev"},
        {"branch_name": "staging", "job_name": "test-project-staging"}
    ],
    "branch_patterns": [
        {"pattern": "feature/*", "job_name": "test-project-feature"},
        {"pattern": "hotfix/*", "job_name": "test-project-hotfix"}
    ]
}

success = asyncio.run(db_service.create_project_mapping(mapping_data))
print(f"Mapping created: {'Success' if success else 'Failed'}")
```

Run the script:

```bash
python create_mapping.py
```

### View Trigger Logs

Refer to the API documentation for log query endpoints.

## 📊 Monitoring and Logs

### View Logs

```bash
# View application logs
tail -n 50 logs/service.log

# View Celery logs
tail -n 50 logs/celery.log
```

### Monitoring Dashboard

Use Grafana to create a monitoring dashboard:
1. Visit http://localhost:3000 (Grafana)
2. Username: `admin`, Password: `admin`
3. Add Prometheus data source: http://prometheus:9090
4. Import monitoring dashboard

### Key Metrics
- **webhook_requests_total**: Total webhook requests
- **webhook_request_duration_seconds**: Request response time
- **queue_size**: Queue length
- **dedup_hits_total**: Deduplication hit count

## 🔧 Troubleshooting

### Common Issues

#### 1. Redis Connection Failure

```bash
# Check Redis status
docker ps | grep redis

# Restart Redis
docker restart webhook-ambassador-redis
```

#### 2. Celery Worker Fails to Start

```bash
# Check Celery configuration
cat .env

# Restart Worker
celery -A app.tasks.jenkins_tasks worker --loglevel=info
```

#### 3. Jenkins Connection Failure

Check Jenkins URL, username, and token in the configuration file.