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

🚀 Gitea Webhook Ambassador Usage Guide

📋 Table of Contents

1. Quick Start
2. Configuration
3. API Endpoints
4. Database Management
5. Monitoring and Logs
6. Troubleshooting

🚀 Quick Start

1. Environment Preparation

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

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

Required configuration:

# Jenkins configuration
JENKINS_USERNAME=your_jenkins_username
JENKINS_TOKEN=your_jenkins_token

# Security configuration
SECURITY_SECRET_KEY=your_secret_key

3. Start Service

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

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

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:

POST /webhook/gitea

Health Check

GET /health
GET /health/queue
GET /health/jenkins

Example response:

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

GET /admin/queue/status

Example response:

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

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:

python create_mapping.py

View Trigger Logs

Refer to the API documentation for log query endpoints.

📊 Monitoring and Logs

View Logs

# 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

# Check Redis status
docker ps | grep redis

# Restart Redis
docker restart webhook-ambassador-redis

2. Celery Worker Fails to Start

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