CFTunnels/docs/UPDATE-PROCESS.md

OpenRewrite Update Process Documentation

Overview

This document describes the automated dependency update process for CFTunnels using OpenRewrite with monthly execution and manual review workflow.

Process Flow

1. Monthly Schedule

• Frequency: Monthly on the 1st at 2 AM UTC
• Trigger: Scheduled Gitea workflow
• Manual Trigger: Available via workflow_dispatch for urgent security updates

2. Safety Validation Steps

Pre-Update Checks

1. Environment Validation

   • Check Java 17 toolchain
   • Verify Gradle wrapper integrity
   • Confirm access to required repositories

2. Test Suite Execution

   • Full unit test suite
   • Full integration test suite
   • Performance baseline tests

3. Configuration Validation

   • Application properties integrity
   • Environment variable presence
   • Database connectivity

OpenRewrite Execution

1. Dry Run Mode

   • Preview all proposed changes
   • Generate change report
   • Verify no breaking changes

2. Apply Updates

   • Safe dependency updates only
   • Spring Boot minor versions (3.4.x → 3.5.x)
   • Security patches for Spring ecosystem

Post-Update Validation

1. Test Suite Re-execution

   • All tests must pass
   • Performance regression checks
   • Integration test validation

2. Safety Script Execution

   • Comprehensive compatibility checks
   • Breaking change detection
   • Safety report generation

3. Pull Request Creation

PR Target

• Target Branch: origin/test
• Source Branch: dependency-updates-YYYY-MM
• Review Required: Manual review mandatory

PR Content

• Title: "Monthly dependency updates via OpenRewrite - YYYY-MM"
• Description:
  • Summary of changes applied
  • Test results before and after
  • Safety validation reports
  • Updated dependencies list

Labels

• dependencies
• openrewrite
• monthly-update
• needs-review

4. Manual Review Process

Review Checklist

• Dependency versions are compatible
• No breaking changes introduced
• Test results are green
• Safety reports are clean
• Configuration files remain intact

Approval Workflow

1. Technical Review: Verify dependency compatibility
2. Security Review: Confirm no vulnerabilities introduced
3. Operations Review: Validate deployment readiness

Merge Decision

• Auto-merge: Disabled - always requires manual approval
• Conflict Resolution: Manual intervention required
• Rollback: Available via rollback request template

Dependency Update Rules

Safe Updates (Automatic)

• ✅ Spring Boot minor versions (3.4.x → 3.5.x)
• ✅ SpringDoc OpenAPI compatible versions
• ✅ PostgreSQL driver updates (42.x series)
• ✅ Spring ecosystem security patches
• ✅ Hibernate validator updates

Excluded Updates (Manual Review Required)

• ❌ Spring Boot major versions (4.x)
• ❌ Jakarta EE namespace changes
• ❌ Experimental Spring features
• ❌ Database schema migrations
• ❌ OAuth2 provider configuration changes

Protected Configurations

• 🔒 Cloudflare API integration
• 🔒 Database connection settings
• 🔒 OAuth2 provider endpoints
• 🔒 Custom security configurations
• 🔒 Docker deployment configurations

Rollback Procedures

Emergency Rollback

1. Create Rollback Request

   • Use .github/ISSUE_TEMPLATE/rollback-request.md
   • Specify target version
   • Assess impact severity

2. Rollback Execution

   • Create rollback branch
   • Revert dependency changes
   • Update Docker images
   • Deploy rollback version

3. Post-Rollback Validation

   • Verify functionality restored
   • Run full test suite
   • Monitor production metrics

Manual Override

• Disable automatic updates:

  # In build.gradle, pin versions
  dependencies {
      implementation 'org.springframework.boot:spring-boot-starter:3.4.5'
      // ... other pinned dependencies
  }
  

• Skip monthly update:

  git checkout test
  # Create commit to skip update
  echo "SKIP_UPDATE=true" > .skip-openrewrite
  git add .skip-openrewrite
  git commit -m "Skip OpenRewrite update this month"
  

Monitoring and Alerting

Pre-Update Notifications

• Timing: 3 days before monthly execution
• Channel: Gitea notifications
• Content: Preview of planned updates

Post-Update Notifications

• Timing: Immediately after PR creation
• Channel: Gitea PR notifications
• Content: PR link with test results

Failure Notifications

• Timing: Immediately on failure
• Channel: Gitea issue creation
• Content: Error details and rollback instructions

Configuration Files

OpenRewrite Configuration

• File: rewrite.yml
• Recipes: Safe dependency updates only
• Exclusions: Experimental features, breaking changes

CI/CD Configuration

• File: .gitea/workflows/rewrite-updates.yml
• Schedule: Monthly cron trigger
• Safety: Full test suite before/after updates

Safety Script

• File: scripts/rewrite-safety-check.sh
• Purpose: Additional validation checks
• Execution: Pre and post-update validation

Success Metrics

Automated Metrics

• Number of successful monthly updates
• Time from update to merge
• Test pass rate percentage
• Rollback frequency

Manual Metrics

• Review time duration
• Manual intervention frequency
• Configuration adjustments needed
• Security update effectiveness

Troubleshooting

Common Issues

Build Failures

# Check for compilation errors
./gradlew compileJava

# Review dependency conflicts
./gradlew dependencies

# Check for version conflicts
./gradlew dependencyInsight --dependency spring-boot-starter

Test Failures

# Run specific failing test
./gradlew test --tests "com.example.FailingTest"

# Run with debug output
./gradlew test --debug

# Check test reports
open build/reports/tests/test/index.html

Integration Test Issues

# Run integration tests only
./gradlew integrationTestOnly

# Check test database setup
# Review application-test.properties

Getting Help

1. Rollback Request: Use rollback issue template
2. Configuration Review: Create issue with configuration label
3. Test Failures: Create issue with tests label and include test reports
4. Urgent Issues: Mention @mentions in issue for immediate attention

Maintenance

Monthly Tasks

• Review update success rate
• Update OpenRewrite recipes if needed
• Review safety script effectiveness
• Update documentation based on learnings

Quarterly Tasks

• Review dependency update strategy
• Update safety exclusion rules
• Review rollback procedures effectiveness
• Update monitoring and alerting configurations

Annual Tasks

• Major version migration planning
• OpenRewrite recipe updates
• Security audit of update process
• Process optimization review

Contact and Support

Process Questions

• Create issue with process label
• Tag relevant team members
• Provide context and expected outcomes

Technical Issues

• Create issue with technical label
• Include error logs and stack traces
• Specify environment and version details

Security Concerns

• Create issue with security label
• Mark as confidential if needed
• Contact security team directly for urgent matters

---

This document is maintained by the CFTunnels team. Last updated: $(date +%Y-%m-%d)