Skip to main content

CI/CD Automation - API Specification

Introduction​

This API specification documents the programmatic interfaces for the CI/CD Automation module of Codomyrmex. The module provides comprehensive continuous integration and deployment capabilities, including pipeline management, automated testing, deployment orchestration, and build automation for the Codomyrmex ecosystem.

Functions​

Function: create_pipeline(name: str, stages: List[Dict], config: Optional[Dict] = None, **kwargs) -> Pipeline​

  • Description: Create and configure a CI/CD pipeline with specified stages and configuration.
  • Parameters:
    • name: Unique pipeline name identifier.
    • stages: List of pipeline stage configurations with jobs and tasks.
    • config: Optional pipeline-level configuration (triggers, environments, etc.).
    • **kwargs: Additional pipeline configuration options.
  • Return Value: Configured Pipeline object ready for execution.
  • Errors: Raises ValueError for invalid configurations and RuntimeError for system errors.

Function: run_pipeline(pipeline: Pipeline, environment: str = "development", **kwargs) -> Dict​

  • Description: Execute a configured pipeline with full orchestration and monitoring.

  • Parameters:

    • pipeline: Pipeline object to execute.
    • environment: Target deployment environment.
    • **kwargs: Execution-specific parameters (dry_run, timeout, etc.).

  • Return Value:

    {
        "status": "success|failed|cancelled",
        "pipeline_id": <str>,
        "execution_time": <float>,
        "stages_completed": <int>,
        "stages_total": <int>,
        "artifacts": [<list_of_artifacts>],
        "reports": {<execution_reports>}
    }

  • Errors: Raises PipelineExecutionError for execution failures.

Function: manage_deployments(deployment_config: Dict, environment: str, **kwargs) -> Deployment​

  • Description: Handle deployment orchestration with rollback capabilities.
  • Parameters:
    • deployment_config: Deployment configuration including artifacts and targets.
    • environment: Target environment for deployment.
    • **kwargs: Deployment-specific options (strategy, timeout, etc.).
  • Return Value: Deployment object with status tracking and management capabilities.
  • Errors: Raises DeploymentError for deployment failures.

Function: monitor_pipeline_health(pipeline_id: str, **kwargs) -> Dict​

  • Description: Real-time monitoring of pipeline execution health and metrics.

  • Parameters:

    • pipeline_id: ID of pipeline to monitor.
    • **kwargs: Monitoring configuration options.

  • Return Value:

    {
        "pipeline_id": <str>,
        "status": "running|completed|failed",
        "health_score": <float>,
        "current_stage": <str>,
        "progress_percentage": <float>,
        "metrics": {<performance_metrics>},
        "alerts": [<list_of_alerts>]
    }

  • Errors: Raises MonitoringError for monitoring system failures.

Function: generate_pipeline_reports(pipeline_id: str, report_types: List[str] = None, **kwargs) -> Dict​

  • Description: Generate comprehensive pipeline execution reports and analytics.

  • Parameters:

    • pipeline_id: ID of pipeline to report on.
    • report_types: Types of reports to generate (performance, quality, deployment).
    • **kwargs: Report generation options.

  • Return Value:

    {
        "pipeline_id": <str>,
        "reports": {
            "performance": {<performance_data>},
            "quality": {<quality_metrics>},
            "deployment": {<deployment_data>}
        },
        "generated_at": <timestamp>,
        "format": "json|html|pdf"
    }

  • Errors: Raises ReportGenerationError for report creation failures.

Function: handle_rollback(deployment_id: str, strategy: str = "immediate", **kwargs) -> Dict​

  • Description: Execute automated rollback for failed deployments.

  • Parameters:

    • deployment_id: ID of deployment to rollback.
    • strategy: Rollback strategy (immediate, gradual, blue-green).
    • **kwargs: Rollback-specific configuration.

  • Return Value:

    {
        "rollback_id": <str>,
        "status": "initiated|completed|failed",
        "strategy": <str>,
        "execution_time": <float>,
        "rollback_steps": [<list_of_steps>],
        "verification_results": {<rollback_verification>}
    }

  • Errors: Raises RollbackError for rollback execution failures.

Function: optimize_pipeline_performance(pipeline: Pipeline, metrics: Dict, **kwargs) -> Dict​

  • Description: Analyze and optimize pipeline performance based on execution metrics.

  • Parameters:

    • pipeline: Pipeline to optimize.
    • metrics: Performance metrics from previous executions.
    • **kwargs: Optimization configuration options.

  • Return Value:

    {
        "optimized_pipeline": <Pipeline>,
        "performance_improvements": {<improvement_metrics>},
        "recommendations": [<list_of_recommendations>],
        "estimated_gain": <float>
    }

  • Errors: Raises OptimizationError for optimization analysis failures.

Data Structures​

Pipeline​

Represents a CI/CD pipeline configuration:

{
    "id": <str>,
    "name": <str>,
    "stages": [<list_of_PipelineStage>],
    "config": {<pipeline_configuration>},
    "created_at": <timestamp>,
    "status": "draft|active|archived"
}

PipelineStage​

Represents an individual pipeline stage:

{
    "name": <str>,
    "jobs": [<list_of_job_definitions>],
    "dependencies": [<list_of_upstream_stages>],
    "environment": <str>,
    "timeout": <int>,
    "retry_policy": {<retry_configuration>}
}

Deployment​

Represents a deployment configuration and status:

{
    "id": <str>,
    "pipeline_id": <str>,
    "environment": <str>,
    "artifacts": [<list_of_artifacts>],
    "status": "pending|in_progress|completed|failed|rolled_back",
    "start_time": <timestamp>,
    "end_time": <timestamp>,
    "rollback_available": <bool>
}

Environment​

Represents a deployment environment:

{
    "name": <str>,
    "type": "development|staging|production",
    "config": {<environment_specific_config>},
    "endpoints": [<list_of_service_endpoints>],
    "credentials": {<secure_credential_references>}
}

PipelineReport​

Represents comprehensive pipeline execution analytics:

{
    "pipeline_id": <str>,
    "execution_id": <str>,
    "duration": <float>,
    "success_rate": <float>,
    "stage_metrics": {<per_stage_metrics>},
    "quality_metrics": {<code_quality_data>},
    "performance_metrics": {<execution_performance>},
    "generated_at": <timestamp>
}

RollbackStrategy​

Defines rollback execution strategy:

{
    "type": "immediate|gradual|blue_green",
    "backup_retention": <int>,
    "verification_steps": [<list_of_verification_steps>],
    "timeout": <int>,
    "notification_channels": [<list_of_channels>]
}

Error Handling​

All functions follow consistent error handling patterns:

  • Configuration Errors: ValueError for invalid parameters or configurations
  • Execution Errors: PipelineExecutionError, DeploymentError, RollbackError
  • System Errors: RuntimeError for underlying system failures
  • Monitoring Errors: MonitoringError for health monitoring failures
  • Reporting Errors: ReportGenerationError for report creation issues
  • Optimization Errors: OptimizationError for performance analysis failures

Integration Patterns​

With Build Synthesis​

from codomyrmex.ci_cd_automation import create_pipeline
from codomyrmex.ci_cd_automation.build import validate_build_config

# Describe and validate the build target
build_config = {"name": "my_app", "build_commands": [["uv", "build"]]}
is_valid, errors = validate_build_config(build_config)

# Create pipeline with build stage (config mapping or YAML/JSON path)
pipeline = create_pipeline({
    "name": "app_pipeline",
    "stages": [
        {"name": "build", "jobs": [{"name": "build", "commands": ["uv build"]}]},
        {"name": "test", "jobs": [{"name": "test", "commands": ["uv run pytest"]}]},
        {"name": "deploy", "jobs": [...]},
    ],
})

With Project Orchestration​

from codomyrmex.logistics.orchestration.project import execute_workflow
from codomyrmex.ci_cd_automation import run_pipeline

# Execute full CI/CD workflow
result = execute_workflow("ci_cd_pipeline", {
    "ci_cd_automation": {
        "pipeline_name": "production_deploy",
        "environment": "production",
        "quality_gates": True
    }
})

Security Considerations​

  • Credential Management: Pipeline configurations may contain sensitive credentials
  • Access Control: Pipeline execution should be restricted based on user permissions
  • Audit Logging: All pipeline activities are logged for compliance and debugging
  • Secure Rollbacks: Rollback operations maintain data integrity and security
  • Environment Isolation: Deployments are isolated between environments for security

Performance Characteristics​

  • Scalability: Supports concurrent pipeline execution
  • Resource Efficiency: Intelligent resource allocation and cleanup
  • Monitoring Overhead: Minimal performance impact from monitoring systems
  • Caching: Build artifacts and test results are cached for efficiency
  • Parallelization: Pipeline stages can execute in parallel when dependencies allow