website/FORGEJO_ACTIONS_SETUP.md

# Forgejo Actions CI/CD Setup for Pricing Tests

## Overview

I've created a comprehensive Forgejo Actions CI/CD setup that automatically runs your pricing tests whenever code changes are made. This ensures that your pricing calculations remain accurate and prevents regressions from being introduced into production.

## Files Created

### Workflow Files
1. **`.forgejo/workflows/ci.yml`** - Main CI/CD pipeline (208 lines)
2. **`.forgejo/workflows/pricing-tests.yml`** - Dedicated pricing tests (297 lines)  
3. **`.forgejo/workflows/pr-pricing-validation.yml`** - Pull request validation (234 lines)
4. **`.forgejo/workflows/scheduled-pricing-tests.yml`** - Daily scheduled tests (359 lines)

### Documentation and Utilities
5. **`.forgejo/workflows/README.md`** - Comprehensive workflow documentation
6. **`.forgejo/setup-local-testing.sh`** - Local testing setup script

## Workflow Features

### 🚀 Main CI/CD Pipeline (`ci.yml`)
**Triggers**: Push to main/develop, Pull Requests

**Jobs**:
- **Test Job**: Runs all Django tests including pricing tests with PostgreSQL
- **Lint Job**: Code quality checks with ruff
- **Security Job**: Security scanning with safety and bandit  
- **Build Job**: Docker image building (only on main/develop)
- **Deploy Job**: Production deployment to OpenShift (only on main)

**Key Features**:
- Separates pricing tests into distinct groups for visibility
- Uses PostgreSQL service for realistic database testing
- Only builds and deploys if all tests pass
- Includes comprehensive Django system checks

### 🧮 Pricing-Specific Tests (`pricing-tests.yml`)
**Triggers**: Changes to pricing-related files
- `hub/services/models/pricing.py`
- `hub/services/tests/test_pricing*.py`
- `hub/services/forms.py`
- `hub/services/views/**`
- `hub/services/templates/**`

**Features**:
- **Matrix Testing**: Python 3.12/3.13 × Django 5.0/5.1
- **Performance Testing**: Large dataset calculations and stress tests
- **Coverage Reporting**: Test coverage analysis and HTML reports
- **Sample Validation**: Real pricing scenarios validation
- **Documentation Checks**: Ensures tests are properly documented

### 🔍 Pull Request Validation (`pr-pricing-validation.yml`)
**Triggers**: Pull requests affecting pricing code

**Features**:
- **Migration Detection**: Checks if pricing model changes need migrations
- **Coverage Threshold**: Enforces 85% test coverage minimum
- **Critical Method Analysis**: Detects changes to important pricing methods
- **Backward Compatibility**: Validates that existing APIs still work
- **Test Addition Validation**: Ensures new features have corresponding tests
- **PR Summary Generation**: Creates detailed summaries for reviewers

### 📅 Scheduled Testing (`scheduled-pricing-tests.yml`)
**Triggers**: Daily at 6 AM UTC, Manual dispatch

**Features**:
- **Multi-Database Testing**: SQLite and PostgreSQL matrix
- **Stress Testing**: Concurrent calculations and large datasets
- **Data Integrity Checks**: Validates pricing data consistency
- **Daily Reports**: System health and statistics
- **Automatic Issue Creation**: Creates GitHub issues on failures
- **Performance Monitoring**: Tracks calculation performance over time

## Security and Environment

### Required Secrets
Set these in your Forgejo repository settings:
```yaml
REGISTRY_USERNAME      # Container registry username  
REGISTRY_PASSWORD      # Container registry password
OPENSHIFT_SERVER      # OpenShift server URL
OPENSHIFT_TOKEN       # OpenShift authentication token
```

### Environment Variables
```yaml
REGISTRY: registry.vshn.net
NAMESPACE: vshn-servalafe-prod
DATABASE_URL: # Set automatically by workflows
DJANGO_SETTINGS_MODULE: hub.settings
```

## Test Coverage

The workflows provide comprehensive testing of:

### ✅ Core Pricing Functionality
- Progressive discount calculations with multiple tiers
- Final price calculations including base fees, unit rates, and addons
- Multi-currency support (CHF, EUR, USD)
- Service level pricing differences (Best Effort vs Guaranteed)
- Addon pricing (base fee and unit rate types)

### ✅ Edge Cases and Error Handling
- Zero and negative value handling
- Very large number calculations
- Missing price data scenarios
- Decimal precision edge cases
- Database constraint validation
- Inactive discount model behavior

### ✅ Integration Scenarios
- Complete service setups with all components
- Real-world pricing scenarios (e.g., PostgreSQL with 16GB RAM)
- External price comparisons with competitors
- Cross-model relationship validation

### ✅ Performance and Stress Testing
- Large dataset calculations (up to 5000 units)
- Concurrent price calculations (50 simultaneous)
- Complex discount models with multiple tiers
- Performance regression detection

## Usage Examples

### Automatic Triggers
```bash
# Trigger full CI/CD pipeline
git push origin main

# Trigger pricing-specific tests
git push origin feature/pricing-improvements

# Trigger PR validation
git checkout -b feature/new-pricing
# Make changes to pricing files
git push origin feature/new-pricing
# Create pull request
```

### Manual Triggers
- Use Forgejo Actions UI to manually run workflows
- Scheduled tests can be run with different scopes:
  - `all` - All pricing tests
  - `pricing-only` - Basic pricing tests only  
  - `integration-only` - Integration tests only

### Local Testing
```bash
# Run local validation before pushing
./.forgejo/setup-local-testing.sh
```

## Monitoring and Alerts

### Test Results
- **Real-time feedback**: See test results in PR checks
- **Detailed logs**: Comprehensive logging with grouped output
- **Coverage reports**: HTML coverage reports as downloadable artifacts
- **Performance metrics**: Timing data for all calculations

### Failure Handling
- **PR blocking**: Failed tests prevent merging
- **Issue creation**: Scheduled test failures automatically create GitHub issues
- **Notification**: Team notifications on critical failures
- **Artifact preservation**: Test results saved for 30 days

## Integration with Existing CI/CD

### Relationship with GitLab CI
Your existing `.gitlab-ci.yml` focuses on:
- Docker image building
- Production deployment
- Simple build-test-deploy workflow

The new Forgejo Actions provide:
- **Comprehensive testing** with multiple scenarios
- **Detailed validation** of pricing-specific changes
- **Matrix testing** across Python/Django versions
- **Automated quality gates** with coverage thresholds
- **Continuous monitoring** with scheduled tests

Both systems can coexist and complement each other.

## Best Practices

### For Developers
1. **Run tests locally** using the setup script before pushing
2. **Add tests** for any new pricing functionality
3. **Check coverage** to ensure adequate test coverage
4. **Review PR summaries** for detailed change analysis

### For Maintainers
1. **Monitor scheduled tests** for early issue detection
2. **Review coverage trends** to maintain quality
3. **Update thresholds** as the codebase evolves
4. **Investigate failures** promptly to prevent regressions

## Benefits

### 🛡️ Regression Prevention
- Comprehensive test suite catches pricing calculation errors
- Matrix testing ensures compatibility across versions
- Backward compatibility checks prevent API breakage

### 🔍 Quality Assurance
- 85% minimum test coverage enforced
- Code quality checks with ruff
- Security scanning with safety and bandit
- Documentation completeness validation

### 📊 Continuous Monitoring
- Daily health checks catch issues early
- Performance regression detection
- Data integrity validation
- Automatic issue creation for failures

### 🚀 Developer Experience
- Fast feedback on pricing changes
- Detailed PR summaries for reviewers
- Local testing script for pre-push validation
- Clear documentation and troubleshooting guides

## Next Steps

1. **Set up secrets** in your Forgejo repository settings
2. **Test locally** using `./.forgejo/setup-local-testing.sh`
3. **Push changes** to trigger the workflows
4. **Monitor results** in the Actions tab
5. **Customize** workflows based on your specific needs

The system is designed to be robust, comprehensive, and maintainable, ensuring that your pricing calculations remain accurate as your codebase evolves.