# 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 ```bash # 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 ```bash # 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: ```bash # 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:** ```groovy // Your existing Jenkinsfile components = [ [ name: 'chat', language: 'python', dependenciesManager: 'pip', buildAgentImage: 'python:3.10-slim-buster', lintEnabled: false, sastEnabled: false ] ] ``` **Parsed Configuration:** ```bash 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: ```bash # 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 ```python # Tests component health endpoint response = requests.get('http://localhost:8000/health', timeout=5) assert response.status_code == 200 ``` #### API Endpoint Tests ```python # 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 ```python # Component-specific integration tests # - Chat: Tests chat service connectivity # - Authentication: Tests auth service functionality # - Central Storage: Tests storage service operations ``` #### Performance Tests (Production Mode) ```python # 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: ```groovy // 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** ```bash cd ~/devbox/freeleaps/apps/chat # Make code changes ``` 2. **Local Unit Testing** ```bash python -m pytest tests/ -v ``` 3. **CI/CD Integration Testing** ```bash # Package and run CI/CD tests devbox package --component=chat --run-cicd-tests=true ``` 4. **Production Mode Testing** ```bash # Test production-ready container devbox package --component=chat --test-mode=production --run-cicd-tests=true ``` 5. **Submit to CI/CD** ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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** ```bash docker logs cicd-test-chat ``` 2. **Inspect Test Network** ```bash docker network inspect devbox-cicd-test-network ``` 3. **Check Dependency Containers** ```bash docker ps | grep cicd- ``` 4. **Manual Test Execution** ```bash # 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.