feat: implement deployment guard workflow

[dcolina]

Deployment Guard Workflow - Initial Release

Summary

This PR introduces a new reusable workflow called deployment-guard.yml that provides configurable deployment validation for Kubernetes manifests. The workflow enforces guardrails around file changes, YAML structure modifications, and container image updates.

Key Features

🔧 Configurable Validation Checks

Three independent validation stages that can be enabled/disabled:

1. File Allowlist (enable_file_allowlist)

   • Restricts which files can be modified using glob patterns
   • Blocks PRs that modify files outside the allowlist

2. Image-Only Changes (enable_image_only_check)

   • Ensures only container image fields are modified
   • Blocks PRs that change infrastructure, resources, or other YAML fields

3. Image Validation (enable_image_validation)

   • Validates image repository, version pattern, and existence
   • Supports custom regex patterns for version formats
   • Optional Docker registry verification

📦 Flexible Configuration

All parameters are optional with sensible defaults:

inputs:
  # Validation toggles
  enable_file_allowlist: true (default)
  enable_image_only_check: true (default)
  enable_image_validation: true (default)
  
  # Configuration
  allowed_files_pattern: '**/*' (default: all files)
  allowed_image_repositories: '' (default: no restriction)
  allowed_version_pattern: '.*' (default: any version)
  verify_image_existence: false (default: skip verification)

🎯 Use Cases

Strict Validation (all checks enabled):

uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: true
  enable_image_only_check: true
  enable_image_validation: true
  allowed_files_pattern: 'kubernetes/**/statefulset.yaml'
  allowed_image_repositories: 'mycompany/myapp'
  allowed_version_pattern: '^(2[5-9]|[3-9][0-9])\.[0-9]{2}\.[0-9]{2}'
  verify_image_existence: true

File Allowlist Only:

uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: true
  enable_image_only_check: false
  enable_image_validation: false
  allowed_files_pattern: 'apps/**/deployment.yaml'

Image Validation Only:

uses: dotCMS/ai-workflows/.github/workflows/deployment-guard.yml@v1.0.0
with:
  enable_file_allowlist: false
  enable_image_only_check: false
  enable_image_validation: true
  allowed_image_repositories: 'org/app1,org/app2'
  allowed_version_pattern: '^\d+\.\d+\.\d+$'

Implementation Details

4-Stage Validation Pipeline

1. validate-changed-files (conditional)

   • Detects files modified in PR
   • Validates against glob pattern allowlist
   • Blocks if unauthorized files changed

2. validate-image-only-changed (conditional)

   • Extracts old and new YAML from changed files
   • Normalizes by replacing images with placeholders
   • Compares normalized YAMLs
   • Blocks if any non-image fields changed

3. validate-images (conditional)

   • Validates image format (repo/name:tag)
   • Checks repository against allowlist
   • Validates version against regex pattern
   • Optionally verifies image exists in registry

4. finalize-validation (always runs)

   • Aggregates results from all validation stages
   • Posts detailed comment to PR
   • Sets final pass/fail status

Cross-Platform Compatibility

• Uses # as sed delimiter for macOS/Linux compatibility
• Forces decimal number interpretation with 10# prefix
• Handles both .yaml and .yml extensions
• Supports glob patterns: **, *, ?

Security Features

• Automated blocking (no manual override possible)
• Detailed validation feedback in PR comments
• Comprehensive error messages with remediation steps
• Safe handling of empty/missing fields

Testing

Comprehensive test coverage includes:

• File allowlist validation (valid/invalid patterns)
• Image-only change detection
• Multi-format version patterns
• Repository allowlist enforcement
• Image existence verification
• Cross-platform compatibility

Next Steps

After merging:

1. Create version tag:

   git checkout main
   git pull origin main
   git tag -a v1.0.0 -m "Release: Deployment Guard v1.0.0"
   git push origin v1.0.0

2. Update downstream repositories to reference @v1.0.0

3. Configure branch protection rules to require status checks

Documentation

Complete documentation available in consuming repositories:

• Setup guide with 6 test scenarios
• Troubleshooting section
• Customization examples
• Security considerations

---

Release Version: v1.0.0
Issue: #339
Type: New Feature

[yolabingo]

should files be json or is empty string ok?

echo "files=[]" >> "$GITHUB_OUTPUT"

[spbolton]

@yolabingo GiTHUB_OUTPUT acts like an appendable properties file it is not yaml.

[spbolton]

I see now though we are treating the value as yaml.

[yolabingo]

The else case there (if files are found) returned a json array. I wasn't sure if whatever ingested this output assumed that files would contain json.

[yolabingo]

chatGPT suggested this, not sure if it is correct:

On push events, BASE_SHA/HEAD_SHA didn’t correctly reflect the commit range

Better to use ${{ github.event.before }} and ${{ github.event.after }}

[yolabingo]

I added some comments but approved to keep you unblocked.

[dcolina]

Thanks @yolabingo for the review feedback! I've addressed both comments in commit 3c86caf:

1. Line 198: Changed from empty string to JSON empty array for consistent format
2. Line 191: Using github.event.before and github.event.after for push events instead of default branch comparison

Both changes improve correctness and data handling. Please let me know if there's anything else to address!