upskill-event-manager/docs/FORGEJO-ACTIONS-SETUP-GUIDE.md

Forgejo Actions CI/CD Setup Guide

Successfully implemented comprehensive CI/CD pipeline for HVAC Community Events WordPress plugin

🚀 Implementation Summary

✅ Completed Tasks

1. Repository Migration: Full GitHub → Forgejo migration with complete history preservation
2. CI/CD Pipeline: Comprehensive Forgejo Actions workflows implemented
3. Security Integration: Multi-layer security scanning and compliance monitoring
4. GitOps Workflows: Automated deployment with rollback capabilities

📁 Pipeline Structure

Primary Workflows

.forgejo/workflows/
├── ci.yml                    # Main CI/CD pipeline
├── gitops.yml               # GitOps deployment automation  
└── security-monitoring.yml  # Security scanning & compliance

🔧 Pipeline Features

1. Main CI/CD Pipeline (ci.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main
• Daily security scans (2 AM UTC)

Jobs:

• Security Scan: PHPCS Security Audit, Semgrep, credential detection
• Code Quality: WordPress Coding Standards, PHPStan, PHPMD
• Unit Tests: PHPUnit with WordPress test framework
• Integration Tests: Playwright E2E tests with WordPress setup
• Deploy Staging: Automated staging deployment (develop branch)
• Deploy Production: Manual approval required (main branch with [deploy-production])

2. GitOps Deployment (gitops.yml)

Capabilities:

• Manual and automated deployments
• Environment-specific configurations (staging/production)
• Pre-deployment validation and health checks
• Automatic backup creation before deployment
• One-click rollback to previous versions
• Post-deployment verification

Supported Actions:

• deploy: Deploy to staging or production
• rollback: Rollback to previous backup
• health-check: Comprehensive environment validation

3. Security Monitoring (security-monitoring.yml)

Scans:

• Daily: Dependency vulnerabilities, secrets detection
• Weekly: Comprehensive OWASP Top 10 compliance audit
• On Push: WordPress security patterns, code analysis

Tools Integrated:

• NPM Audit & Composer Security Checker
• detect-secrets & TruffleHog for credential scanning
• Semgrep for static code analysis
• WordPress-specific security patterns
• OWASP compliance validation

🔒 Security Configuration Required

Repository Secrets Setup

Navigate to your Forgejo repository → Settings → Secrets and add:

Staging Environment

STAGING_SSH_KEY          # SSH private key for staging server
STAGING_HOST             # upskill-staging.measurequick.com
STAGING_SSH_USER         # root
STAGING_WP_PATH          # /var/www/html
STAGING_URL              # https://upskill-staging.measurequick.com

Production Environment

PRODUCTION_SSH_KEY       # SSH private key for production server
PRODUCTION_HOST          # 146.190.76.204 or upskillhvac.com
PRODUCTION_SSH_USER      # benr
PRODUCTION_WP_PATH       # /var/www/html
PRODUCTION_URL           # https://upskillhvac.com

SSH Key Generation (If Needed)

# Generate deployment key
ssh-keygen -t ed25519 -C "forgejo-actions-deployment" -f deployment_key

# Add public key to server authorized_keys
cat deployment_key.pub >> ~/.ssh/authorized_keys

# Add private key to Forgejo repository secrets
cat deployment_key  # Copy to STAGING_SSH_KEY or PRODUCTION_SSH_KEY

🚀 Deployment Workflows

Automatic Deployment

Staging: Automatic on push to develop branch

git push origin develop  # Triggers staging deployment

Production: Manual approval required

git commit -m "feat: new feature [deploy-production]"
git push origin main  # Requires manual approval in Actions

Manual Deployment via API

# Deploy to staging
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"deploy-staging","client_payload":{"environment":"staging","action":"deploy"}}' \
  https://git.tealmaker.com/api/v1/repos/ben/upskill-event-manager/dispatches

# Deploy to production  
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"deploy-production","client_payload":{"environment":"production","action":"deploy"}}' \
  https://git.tealmaker.com/api/v1/repos/ben/upskill-event-manager/dispatches

# Rollback staging
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"deploy-staging","client_payload":{"environment":"staging","action":"rollback"}}' \
  https://git.tealmaker.com/api/v1/repos/ben/upskill-event-manager/dispatches

Manual Deployment via Forgejo UI

1. Navigate to Actions tab in repository
2. Select GitOps Deployment Automation workflow
3. Click Run workflow
4. Choose:
   • Environment: staging or production
   • Action: deploy, rollback, or health-check
   • Version: specific tag/commit (optional)

📊 Monitoring & Compliance

Security Dashboard

Daily Reports: Automated vulnerability scanning Weekly Audits: Comprehensive OWASP Top 10 compliance Real-time Alerts: Critical security issues trigger immediate notifications

Available Reports

Access via Actions → Artifacts after pipeline runs:

• security-report: Semgrep and vulnerability analysis
• coverage-report: PHPUnit test coverage
• integration-test-results: E2E test results and screenshots
• dependency-scan-reports: NPM and Composer vulnerability reports
• secrets-scan-reports: Credential exposure analysis
• final-security-report: Comprehensive security summary

🔧 Local Development Integration

Running Tests Locally

# Security scan
composer global require automattic/phpcs-security-audit
phpcs --standard=Security --extensions=php .

# Unit tests  
phpunit --coverage-html=coverage/

# Integration tests
HEADLESS=true node test-master-trainer-e2e.js

Pre-commit Validation

# Use existing validation script
./scripts/pre-deployment-check.sh

# Or run individual checks
phpcs --standard=WordPress --extensions=php .
npm audit --audit-level=moderate

🚨 Emergency Procedures

Quick Rollback

If production deployment fails:

1. Via Forgejo UI:

   • Actions → GitOps Deployment → Run workflow
   • Environment: production, Action: rollback

2. Via Command Line:

   ./scripts/deploy.sh production rollback
   

Health Check

Verify environment status:

# Via pipeline
curl -X POST -H "Authorization: token YOUR_TOKEN" \
  -d '{"event_type":"deploy-production","client_payload":{"environment":"production","action":"health-check"}}' \
  https://git.tealmaker.com/api/v1/repos/ben/upskill-event-manager/dispatches

# Via script
./scripts/deploy.sh production health-check

🎯 Next Steps

Phase 2: Test Framework Migration (Pending)

1. Migrate 80+ Test Files: Convert to new Page Object Model architecture
2. Setup Test Environments: Docker Compose for hermetic testing
3. Implement Test Data Management: Automated seeding and cleanup
4. Performance Optimization: Parallel execution and storage state caching

Phase 3: Advanced GitOps

1. Multi-environment Support: Dev, staging, production pipeline
2. Blue-Green Deployments: Zero-downtime deployment strategy
3. Canary Releases: Gradual rollout with monitoring
4. Infrastructure as Code: Terraform integration

📚 Documentation References

• Pipeline Configuration: .forgejo/workflows/ directory
• Security Framework: docs/SECURITY-INCIDENT-REPORT.md
• Test Modernization Plan: docs/COMPREHENSIVE-TESTING-MODERNIZATION-PLAN.md
• WordPress Best Practices: docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md

---

Status: ✅ IMPLEMENTATION COMPLETE
Date: 2025-08-27
Pipeline Status: 🟢 Active and monitoring
Next Phase: Test framework migration (80+ files)