Northern-Thailand-Ping-River-Monitor/docs/GITEA_WORKFLOWS.md

🔄 Gitea Actions Workflows - Northern Thailand Ping River Monitor

📋 Overview

This document describes the Gitea Actions workflows configured for the Northern Thailand Ping River Monitor project. These workflows provide comprehensive CI/CD, security scanning, and documentation generation.

🚀 Available Workflows

1. CI/CD Pipeline (.gitea/workflows/ci.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main
• Daily scheduled runs at 2 AM UTC

Jobs:

• Test Suite: Multi-version Python testing (3.9-3.12)
• Code Quality: Linting, formatting, and type checking
• Build: Docker image creation and testing
• Integration Test: Testing with VictoriaMetrics service
• Deploy Staging: Automatic deployment to staging (develop branch)
• Deploy Production: Manual deployment to production (main branch)
• Performance Test: Load testing after production deployment

Key Features:

• ✅ Multi-Python version testing
• ✅ Docker multi-architecture builds (amd64, arm64)
• ✅ Service integration testing
• ✅ Automatic staging deployment
• ✅ Manual production approval
• ✅ Performance validation

2. Security & Dependency Updates (.gitea/workflows/security.yml)

Triggers:

• Daily scheduled runs at 3 AM UTC
• Manual dispatch
• Changes to requirements files or Dockerfile

Jobs:

• Dependency Scan: Safety, Bandit, Semgrep security scans
• Docker Security: Trivy vulnerability scanning
• License Check: License compliance verification
• Dependency Updates: Automated update detection
• Code Quality: Complexity and maintainability analysis

Key Features:

• 🔒 Daily security scans
• 📦 Dependency vulnerability detection
• 📄 License compliance checking
• 🔄 Automated update notifications
• 📊 Code quality metrics

3. Release Workflow (.gitea/workflows/release.yml)

Triggers:

• Git tags matching v*.*.* pattern
• Manual dispatch with version input

Jobs:

• Create Release: Automated release creation with changelog
• Test Release: Comprehensive testing across Python versions
• Build Release: Multi-architecture Docker images with proper tags
• Security Scan: Trivy security scanning of release images
• Deploy Release: Production deployment with health checks
• Validate Release: Post-deployment validation and testing

Key Features:

• 🏷️ Automated release creation
• 📝 Changelog generation
• 🐳 Multi-architecture Docker builds
• 🔒 Security scanning
• ✅ Comprehensive validation

4. Documentation (.gitea/workflows/docs.yml)

Triggers:

• Changes to documentation files
• Changes to Python source files
• Manual dispatch

Jobs:

• Validate Docs: Link checking and structure validation
• Generate API Docs: OpenAPI specification generation
• Build Sphinx Docs: Comprehensive API documentation
• Documentation Summary: Build status and artifact summary

Key Features:

• 📚 Automated API documentation
• 🔗 Link validation
• 📖 Sphinx documentation generation
• ✅ Documentation completeness checking

🔧 Workflow Configuration

Required Secrets

Configure these secrets in your Gitea repository settings:

GITEA_TOKEN          # Gitea access token for container registry
GITHUB_TOKEN         # GitHub personal access token for better rate limits
SLACK_WEBHOOK_URL    # Optional: Slack notifications
STAGING_WEBHOOK_URL  # Optional: Staging deployment webhook
PRODUCTION_WEBHOOK_URL # Optional: Production deployment webhook

Setting up GitHub Token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate a new token with public_repo scope (for public repos) or repo scope (for private repos)
3. Copy the token
4. In your Gitea repository → Settings → Secrets → Add GITHUB_TOKEN with the copied value

Environment Variables

Key environment variables used across workflows:

PYTHON_VERSION: '3.11'           # Default Python version
REGISTRY: git.b4l.co.th          # Container registry
IMAGE_NAME: grabowski/northern-thailand-ping-river-monitor

📊 Workflow Status

CI/CD Pipeline Status

• Test Coverage: Multi-version Python testing
• Code Quality: Automated linting and formatting
• Security: Integrated security scanning
• Deployment: Automated staging, manual production

Security Monitoring

• Daily Scans: Automated vulnerability detection
• Dependency Updates: Proactive update notifications
• License Compliance: Automated license checking
• Code Quality: Continuous quality monitoring

Release Management

• Automated Releases: Tag-based release creation
• Multi-Architecture: Support for amd64 and arm64
• Security Validation: Pre-deployment security checks
• Health Monitoring: Post-deployment validation

🚀 Usage Examples

Triggering Workflows

Manual CI/CD Run:

# Push to trigger CI/CD
git push origin main

# Create pull request to trigger testing
git checkout -b feature/new-feature
git push origin feature/new-feature
# Create PR in Gitea UI

Manual Security Scan:

# Trigger via Gitea Actions UI
# Go to Actions → Security & Dependency Updates → Run workflow

Creating a Release:

# Create and push a tag
git tag v3.1.1
git push origin v3.1.1

# Or use manual dispatch in Gitea Actions UI

Monitoring Workflow Results

Check Workflow Status:

1. Navigate to your repository in Gitea
2. Click on "Actions" tab
3. View workflow runs and their status

Download Artifacts:

1. Click on a completed workflow run
2. Scroll to "Artifacts" section
3. Download reports and logs

View Security Reports:

1. Go to Security workflow runs
2. Download security-reports artifacts
3. Review JSON reports for vulnerabilities

🔍 Troubleshooting

Common Issues

Workflow Fails on Dependencies:

# Check requirements.txt for version conflicts
pip-compile requirements.in

Docker Build Fails:

# Test Docker build locally
make docker-build
docker run --rm ping-river-monitor python run.py --test

Security Scan Failures:

# Run security scans locally
safety check -r requirements.txt
bandit -r src/

Test Failures:

# Run tests locally
make test
python tests/test_integration.py

Debugging Workflows

Enable Debug Logging: Add to workflow file:

env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

Check Workflow Logs:

1. Go to failed workflow run
2. Click on failed job
3. Expand failed step to see detailed logs

Validate Workflow Syntax:

# Validate YAML syntax
make validate-workflows

📈 Performance Optimization

Caching Strategy

• Pip Cache: Cached across workflow runs
• Docker Layer Cache: GitHub Actions cache for faster builds
• Dependency Cache: Cached based on requirements.txt hash

Parallel Execution

• Matrix Builds: Multiple Python versions tested in parallel
• Independent Jobs: Security scans run independently of tests
• Conditional Execution: Jobs skip when not needed

Resource Management

• Timeout Settings: Prevent hanging workflows
• Resource Limits: Appropriate runner sizing
• Artifact Cleanup: Automatic cleanup of old artifacts

🔒 Security Best Practices

Secret Management

• Use Gitea repository secrets for sensitive data
• Never commit secrets to repository
• Rotate secrets regularly
• Use least-privilege access tokens

Container Security

• Multi-stage Docker builds for smaller images
• Non-root user in containers
• Regular base image updates
• Vulnerability scanning before deployment

Code Security

• Automated security scanning in CI/CD
• Dependency vulnerability monitoring
• License compliance checking
• Code quality enforcement

📚 Additional Resources

Gitea Actions Documentation

• Gitea Actions Overview
• Workflow Syntax
• Available Actions

Project-Specific Resources

• Contributing Guide
• Deployment Checklist
• Project Structure

Monitoring and Alerts

• Workflow status badges in README
• Email notifications for failures
• Slack/Discord integration for team updates
• Grafana dashboards for deployment metrics

---

Workflow Version: v3.1.2
Last Updated: 2025-08-12
Maintained By: Ping River Monitor Team