feat: refactor deployment-guard to v1.1.2 with robust state management

[dcolina]

🎯 Overview

Complete architectural refactor of the Deployment Guard workflow to v2.0.0, eliminating all fragile temporary file-based state management and fixing critical validation bugs.

🚨 Breaking Changes

• verify_image_existence now defaults to true (was false in v1.x)
  • This was always the intended behavior but was disabled due to bugs
  • If you want to disable, explicitly set to false in your workflow configuration

✨ What's New

1. Robust Version Comparison

Complete rewrite of anti-downgrade logic with proper handling of:

• Base version comparison (YY.MM.DD format)
• Rebuild number comparison (e.g., -2 in 25.12.08-2)
• Hash comparison (e.g., _abc123 in 25.12.08_abc123)
• Full support for all combinations: 25.12.08, 25.12.08-2, 25.12.08_abc, 25.12.08-2_abc

2. Improved Registry Validation

• Tries Docker Hub first for canonical images
• Falls back to full image path for private registries
• Better error messages indicating which registry was checked
• Handles mirror registries gracefully

3. Enhanced Error Reporting

• State variables accumulate ALL validation failures before exiting
• Detailed failure reasons for each failed image/file
• Clear indication of which validation step failed and why

🐛 Bugs Fixed

Bug #1: Rebuild Downgrade Not Detected (Critical)

Issue: v1.x allowed downgrade from 25.12.08-2 to 25.12.08
Root Cause: Only compared base version (YY.MM.DD), ignored rebuild numbers
Fix: Now extracts and compares rebuild numbers when base version is the same

Examples:

• ❌ v1.x: 25.12.08-2 → 25.12.08 = ✅ Allowed (BUG)
• ✅ v2.0.0: 25.12.08-2 → 25.12.08 = ❌ Blocked (CORRECT)
• ✅ v2.0.0: 25.12.08 → 25.12.08-2 = ✅ Allowed (upgrade)
• ✅ v2.0.0: 25.12.08-2_abc → 25.12.08-2_xyz = ✅ Allowed (same version, different hash)

Bug #2: Temporary File Race Conditions

Issue: Race conditions with /tmp/validation_failed.txt file
Root Cause: Multiple writes to same file, manual cleanup required
Fix: Eliminated ALL temporary files, using in-memory bash arrays

Bug #3: Image Existence Check Failures

Issue: Validation failed for valid private registry images
Root Cause: Only checked Docker Hub canonical image
Fix: Now tries Docker Hub first, then falls back to full image path

Bug #4: Silent Failures in Validation Loops

Issue: Validation could continue after failures
Root Cause: Lack of strict error handling
Fix: Added set -euo pipefail to all bash scripts

Bug #5: Version Pattern Validation Edge Cases

Issue: Malformed tags could pass validation
Root Cause: Regex didn't enforce proper boundaries
Fix: Improved regex validation with proper format checks

🔧 Technical Changes

State Management Architecture

Before (v1.x): Used temporary files

echo "false" > /tmp/validation_failed.txt
echo "$image" >> /tmp/new_images.txt
[ -f /tmp/validation_failed.txt ] && exit 1

After (v2.0.0): Uses bash arrays

VALIDATION_FAILED=false
FAILED_IMAGES=()
FAILED_IMAGES+=("$image: reason")
if [ "$VALIDATION_FAILED" = "true" ]; then
  printf '   - %s\n' "${FAILED_IMAGES[@]}"
  exit 1
fi

Error Handling

All bash scripts now use strict mode:

set -euo pipefail

📝 Documentation

Added comprehensive CHANGELOG.md with:

• Complete bug details and technical explanations
• Migration guide from v1.x to v2.0.0
• Version support matrix
• Testing recommendations

🧪 Testing

Recommended testing approach:

uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v2.0.0
with:
  testing_force_non_bypass: true  # Force validation even for org members
  verify_image_existence: true    # Now enabled by default

📊 Test Cases Covered

Scenario	v1.x	v2.0.0
25.12.08-2 → 25.12.08	✅ (bug)	❌ (correct)
25.12.08 → 25.12.08-2	✅	✅
25.12.08-2 → 25.12.08-3	✅	✅
25.12.08_abc → 25.12.08_xyz	✅	✅
25.12.07 → 25.12.08	✅	✅
25.12.08 → 25.12.07	❌	❌
Private registry image	❌ (bug)	✅ (fixed)

🔄 Migration Path

1. Week 1: Deploy v2.0.0 to staging/dev
2. Week 2: Monitor and validate test cases
3. Week 3: Deploy to production
4. Week 4: Deprecate v1.x

📚 Related Issues

Fixes bugs reported in Deutsche Bank infrastructure validation.

✅ Checklist

• All temporary files eliminated
• Rebuild downgrade detection fixed
• Private registry support added
• Strict error handling implemented
• Comprehensive CHANGELOG created
• All validation cases tested
• Breaking changes documented

---