freeleaps-pub/devbox/cli/CICD_INTEGRATION.md

CI/CD Integration with DevBox Packaging

Overview

The DevBox packaging feature now includes comprehensive CI/CD integration that allows you to run your existing CI/CD integration tests locally before submitting code to your Jenkins pipeline. This ensures that the same tests that run in your CI/CD environment are executed locally, providing confidence that your code will pass the CI/CD pipeline.

Why CI/CD Integration?

Problem Statement

• CI/CD Failures: Code passes local tests but fails in CI/CD pipeline
• Environment Differences: Local and CI/CD environments are not identical
• Test Inconsistency: Different test suites run locally vs. in CI/CD
• Late Detection: Issues discovered only after code is committed and pushed

Solution Benefits

• Early Detection: Catch CI/CD issues before committing code
• Environment Parity: Test in containers that match CI/CD environment
• Test Consistency: Run the same tests locally as in CI/CD
• Confidence: Ensure code will pass CI/CD pipeline
• Time Saving: Reduce CI/CD iteration cycles

Architecture

CI/CD Integration Components

1. Jenkins Pipeline Configuration Parser

• Automatically detects and parses your Jenkinsfile
• Extracts component configurations (language, dependencies, build settings)
• Maps CI/CD test requirements to local execution

2. CI/CD Test Environment

• Creates isolated Docker networks for testing
• Starts the same dependencies as your CI/CD pipeline
• Configures environment variables to match CI/CD

3. Component-Specific Test Execution

• Runs health checks, API tests, and integration tests
• Executes performance tests for production mode
• Validates component functionality in CI/CD-like environment

4. Test Result Reporting

• Provides detailed test results and logs
• Matches CI/CD test output format
• Identifies specific test failures

Integration with Existing CI/CD Pipeline

Local Development → DevBox Package → CI/CD Tests → Jenkins Pipeline
     ↓                    ↓              ↓              ↓
   Code Changes    Docker Container   Test Results   Production

Usage Examples

Basic CI/CD Integration

# Package with CI/CD integration tests
devbox package --run-cicd-tests=true

# Package specific component with CI/CD tests
devbox package --component=chat --run-cicd-tests=true

# Package for production with CI/CD tests
devbox package --test-mode=production --run-cicd-tests=true

Advanced CI/CD Integration

# Package with both CI/CD and legacy integration tests
devbox package --run-cicd-tests=true --run-integration=true

# Package with custom image tag and CI/CD tests
devbox package --image-tag=v1.2.3 --run-cicd-tests=true

# Package specific component with production mode and CI/CD tests
devbox package --component=authentication --test-mode=production --run-cicd-tests=true

Command Reference

devbox package with CI/CD Integration

New Arguments

• --run-cicd-tests, -j: Run CI/CD integration tests after packaging (default: false)

Complete Argument List

• --working-home, -w: Working home directory (default: $HOME/devbox)
• --image-repo, -r: Docker image repository (default: freeleaps-local)
• --image-tag, -t: Docker image tag (default: timestamp)
• --component, -c: Component to package (default: all components)
• --test-mode, -m: Packaging mode: test or production (default: test)
• --run-integration, -i: Run legacy integration tests (default: false)
• --run-cicd-tests, -j: Run CI/CD integration tests (default: false)

CI/CD Test Execution

1. Jenkins Configuration Parsing

The system automatically detects and parses your Jenkinsfile:

# Looks for Jenkinsfile in these locations:
# - $WORKING_HOME/freeleaps/Jenkinsfile
# - $WORKING_HOME/freeleaps/ci/Jenkinsfile
# - $WORKING_HOME/freeleaps/.jenkins/Jenkinsfile
# - $WORKING_HOME/freeleaps/apps/$component/Jenkinsfile

Example Jenkinsfile Parsing:

// Your existing Jenkinsfile
components = [
  [
    name: 'chat',
    language: 'python',
    dependenciesManager: 'pip',
    buildAgentImage: 'python:3.10-slim-buster',
    lintEnabled: false,
    sastEnabled: false
  ]
]

Parsed Configuration:

language:python
deps_manager:pip
build_image:python:3.10-slim-buster
lint_enabled:false
sast_enabled:false

2. CI/CD Test Environment Setup

The system creates a CI/CD-like test environment:

# Creates isolated test network
docker network create devbox-cicd-test-network

# Starts component-specific dependencies
# For chat, authentication, etc.:
# - MongoDB (mongodb:5.0)
# - Redis (redis:7-alpine)
# - RabbitMQ (rabbitmq:3-management)

# For devsvc:
# - MongoDB (mongodb:5.0)

3. Component-Specific Test Execution

Each component runs through a comprehensive test suite:

Health Check Tests

# Tests component health endpoint
response = requests.get('http://localhost:8000/health', timeout=5)
assert response.status_code == 200

API Endpoint Tests

# Tests common API endpoints
endpoints = ["/health", "/docs", "/openapi.json"]
for endpoint in endpoints:
    response = requests.get(f'http://localhost:8000{endpoint}', timeout=5)
    assert response.status_code in [200, 404]  # 404 OK for optional endpoints

Integration Tests

# Component-specific integration tests
# - Chat: Tests chat service connectivity
# - Authentication: Tests auth service functionality
# - Central Storage: Tests storage service operations

Performance Tests (Production Mode)

# Load testing for production mode
response_times = []
for i in range(10):
    start_time = time.time()
    response = requests.get('http://localhost:8000/health', timeout=5)
    if response.status_code == 200:
        response_times.append(time.time() - start_time)

avg_time = statistics.mean(response_times)
max_time = max(response_times)
assert avg_time < 1.0 and max_time < 2.0

Integration with Your Existing CI/CD Pipeline

1. Jenkins Pipeline Compatibility

The CI/CD integration is designed to work with your existing first-class-pipeline library:

// Your existing Jenkinsfile remains unchanged
library 'first-class-pipeline'

executeFreeleapsPipeline {
  serviceName = 'freeleaps'
  environmentSlug = 'prod'
  serviceGitBranch = 'master'
  serviceGitRepo = "https://gitea.freeleaps.mathmast.com/freeleaps/freeleaps-service-hub.git"
  serviceGitRepoType = 'monorepo'
  serviceGitCredentialsId = 'freeleaps-repos-gitea-credentails'
  executeMode = 'fully'
  commitMessageLintEnabled = false
  components = [
    [
      name: 'authentication',
      root: 'apps/authentication',
      language: 'python',
      dependenciesManager: 'pip',
      // ... other configuration
    ]
  ]
}

2. Test Environment Parity

The local CI/CD tests use the same:

• Dependencies: MongoDB, Redis, RabbitMQ versions
• Environment Variables: Service endpoints, credentials
• Network Configuration: Isolated Docker networks
• Test Execution: Health checks, API tests, integration tests

3. Component Support

Currently supported components:

• chat - Chat service with full dependency stack
• authentication - Authentication service with full dependency stack
• central_storage - Storage service with full dependency stack
• content - Content service with full dependency stack
• notification - Notification service with full dependency stack
• payment - Payment service with full dependency stack
• devsvc - DevSVC with MongoDB dependency

Workflow Integration

Typical Development Workflow with CI/CD Integration

1. Local Development

   cd ~/devbox/freeleaps/apps/chat
   # Make code changes
   

2. Local Unit Testing

   python -m pytest tests/ -v
   

3. CI/CD Integration Testing

   # Package and run CI/CD tests
   devbox package --component=chat --run-cicd-tests=true
   

4. Production Mode Testing

   # Test production-ready container
   devbox package --component=chat --test-mode=production --run-cicd-tests=true
   

5. Submit to CI/CD

   # If all tests pass, commit and push
   git add .
   git commit -m "Feature: Add new chat functionality"
   git push
   

CI/CD Pipeline Integration

Your Jenkins pipeline will now receive code that has been:

• ✅ Tested in production-like containers
• ✅ Validated with CI/CD integration tests
• ✅ Performance tested (if in production mode)
• ✅ Health checked and API tested

Configuration and Customization

1. Custom Test Configuration

You can customize CI/CD test behavior by modifying the test functions:

# Edit the test functions in the devbox script
# - run_health_check_test()
# - run_api_endpoint_tests()
# - run_integration_tests()
# - run_performance_tests()

2. Component-Specific Test Customization

Add component-specific tests by extending the integration test functions:

# Add new component test function
run_custom_component_integration_tests() {
  local container="$1"
  local network="$2"
  
  # Your custom test logic
  docker exec "$container" python -c "
# Your custom test code
"
}

3. Environment Variable Customization

Customize environment variables for specific components:

# Modify setup_component_env_vars() function
case "$component" in
your_custom_component)
  env_array+=(
    "-e" "CUSTOM_VAR=value"
    "-e" "ANOTHER_VAR=value"
  )
  ;;
esac

Troubleshooting

Common CI/CD Integration Issues

1. Jenkinsfile Not Found

   Warning: No Jenkinsfile found for component: chat
   

   Solution: Ensure Jenkinsfile exists in one of the expected locations.

2. Component Not Found in Jenkinsfile

   Warning: Component chat not found in Jenkinsfile
   

   Solution: Check component name matches exactly in Jenkinsfile.

3. CI/CD Test Dependencies Fail

   Error: MongoDB failed to start
   

   Solution: Check Docker resources and network configuration.

4. Health Check Failures

   Error: Health check failed for chat
   

   Solution: Verify component health endpoint is implemented.

Debugging CI/CD Tests

1. Check Test Container Logs

   docker logs cicd-test-chat
   

2. Inspect Test Network

   docker network inspect devbox-cicd-test-network
   

3. Check Dependency Containers

   docker ps | grep cicd-
   

4. Manual Test Execution

   # Run component manually for debugging
   docker run -it --network devbox-cicd-test-network \
     -e MONGODB_URI="mongodb://test:test@cicd-mongodb-chat:27017" \
     your-image-name
   

Best Practices

1. CI/CD Test Development

• Write tests that match your CI/CD pipeline requirements
• Use the same test data and configurations
• Implement proper cleanup and error handling

2. Component Configuration

• Ensure components have proper health endpoints
• Implement comprehensive API documentation
• Use consistent environment variable naming

3. Test Execution

• Run CI/CD tests before committing code
• Use production mode for final validation
• Monitor test execution time and performance

4. Integration with Workflow

• Add CI/CD tests to your development checklist
• Use CI/CD tests for pull request validation
• Integrate with your IDE or editor

Future Enhancements

Planned Features

1. Multi-Component Testing: Test multiple components together
2. Custom Test Suites: Support for custom test configurations
3. Test Result Export: Export test results in CI/CD format
4. Performance Benchmarking: Advanced performance testing
5. Security Scanning: Integrate security testing

Integration Opportunities

1. Git Hooks: Pre-commit CI/CD test validation
2. IDE Integration: VS Code and IntelliJ plugins
3. CI/CD Pipeline Integration: Direct Jenkins integration
4. Monitoring Integration: Test result monitoring and alerting

Conclusion

The CI/CD integration feature bridges the gap between local development and CI/CD pipeline execution by providing engineers with the ability to run the same tests locally that will run in their CI/CD environment. This significantly reduces CI/CD failures and improves development confidence.

By integrating your existing CI/CD integration tests into the DevBox packaging workflow, you can ensure that code is thoroughly tested before it reaches your Jenkins pipeline, leading to faster, more reliable deployments.