Cortex CI/CD System

This document describes the complete GitHub Actions CI/CD pipeline for the Cortex memory tiering system.

Overview

The Cortex project includes comprehensive automated testing and deployment workflows that support cross-platform development on Linux, Windows, and macOS.

Workflows

1. Continuous Integration (.github/workflows/ci.yml)

Triggers:

• Push to any branch
• Pull requests
• Manual dispatch

Platforms: Linux, Windows, macOS

Features:

• Cross-platform builds using CMake
• Kernel module compilation (Linux)
• Native benchmark compilation (all platforms)
• Unit testing
• Cross-platform analysis
• Artifact upload

Key Steps:

1. Platform-specific dependency installation
2. CMake configuration and build
3. Test execution
4. Cross-platform result analysis
5. Build artifact archival

2. Release Automation (.github/workflows/release.yml)

Triggers:

• Git tags matching v*.*.* pattern
• Manual dispatch with version input

Features:

• Automated GitHub releases
• Cross-platform binary packaging
• Source code archival
• Release notes generation

Artifacts:

• cortex-linux-x64.tar.gz - Linux binaries
• cortex-windows-x64.zip - Windows binaries
• cortex-macos-x64.tar.gz - macOS binaries
• cortex-source.tar.gz - Source code archive

3. Performance Testing (.github/workflows/performance.yml)

Triggers:

• Daily schedule (02:00 UTC)
• Manual dispatch with configurable parameters

Parameters:

• platforms: Comma-separated list (linux,windows,macos)
• benchmark_size: Memory size in MB (default: 512)
• iterations: Number of test iterations (default: 10)

Features:

• Cross-platform performance benchmarks
• Statistical analysis and reporting
• Performance trend tracking
• Automated PR comments with results

Jobs:

1. performance-linux: Simulated kernel module performance
2. performance-windows: Native WinBench execution
3. performance-macos: Native macOS benchmark
4. performance-analysis: Cross-platform comparison

Platform-Specific Details

Linux

• Environment: Ubuntu Latest
• Build System: CMake + GCC
• Components: Helios kernel module, examples, tools
• Testing: Simulated performance (actual kernel module requires root)
• Artifacts: ELF binaries, analysis results

Windows

• Environment: Windows Latest
• Build System: CMake + MSVC
• Components: WinBench native benchmark, WinViz GUI
• Testing: Full benchmark execution
• Artifacts: PE executables, performance data

macOS

• Environment: macOS Latest
• Build System: CMake + Clang
• Components: Native benchmark with Mach APIs
• Testing: Full benchmark execution
• Artifacts: Mach-O binaries, performance data

Supporting Scripts

.github/scripts/ci_summary.py

Generates comprehensive CI build summaries with platform status, build artifacts, and cross-platform comparisons.

.github/scripts/linux_perf_sim.py

Simulates Linux kernel module performance for CI environments where actual kernel modules cannot be loaded.

.github/scripts/perf_analysis.py

Analyzes cross-platform performance benchmark results and generates unified reports.

Configuration

Environment Variables

• BUILD_TYPE: Release/Debug build configuration
• BENCHMARK_SIZE: Memory benchmark size in MB
• ITERATIONS: Number of performance test iterations

Matrix Strategy

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    include:
      - os: ubuntu-latest
        platform: linux
      - os: windows-latest  
        platform: windows
      - os: macos-latest
        platform: macos

Artifacts and Retention

Build Artifacts (30 days)

• Cross-platform binaries
• Analysis results
• Test outputs

Performance Reports (90 days)

• Historical performance data
• Cross-platform comparisons
• Statistical analysis

Release Artifacts (Permanent)

• Tagged release binaries
• Source code archives
• Release documentation

Usage Examples

Manual CI Run

# Trigger CI workflow for specific platforms
gh workflow run ci.yml -f platforms="linux,windows"

Performance Testing

# Run performance tests with custom configuration
gh workflow run performance.yml \
  -f platforms="linux,macos" \
  -f benchmark_size="1024" \
  -f iterations="20"

Create Release

# Tag-based release
git tag v1.0.0
git push origin v1.0.0

# Manual release
gh workflow run release.yml -f version="v1.0.1-rc1"

Monitoring and Debugging

Workflow Status

Monitor workflow execution in the GitHub Actions tab:

• Build status and logs
• Artifact downloads
• Performance trends

Common Issues

1. YAML Syntax Errors

   • Validate YAML with yamllint
   • Check heredoc and multiline string formatting

2. Platform Build Failures

   • Review platform-specific dependency installation
   • Check CMake configuration flags

3. Performance Variations

   • Compare against historical baselines
   • Account for CI runner performance variance

Debugging Commands

# Check workflow syntax
yamllint .github/workflows/*.yml

# Test local build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Validate analysis scripts
python3 .github/scripts/perf_analysis.py

Security Considerations

• All workflows use pinned action versions (@v4)
• No sensitive data in public repositories
• Limited token permissions for automated tasks
• Secure artifact handling and retention policies

Future Enhancements

1. Performance Regression Detection

   • Automated baseline comparisons
   • Alert on significant performance degradation

2. Extended Platform Support

   • ARM64 architectures
   • Additional Linux distributions

3. Advanced Analytics

   • Performance trend visualization
   • Automated optimization recommendations

4. Integration Testing

   • Cross-platform compatibility validation
   • End-to-end system testing

Maintenance

Regular Tasks

• Update action versions quarterly
• Review and clean old artifacts
• Update platform dependencies
• Validate performance baselines

Troubleshooting Contacts

• CI/CD Issues: DevOps team
• Performance Analysis: Performance engineering team
• Platform-specific builds: Platform maintainers

---

This CI/CD system provides a robust foundation for the Cortex project's development, testing, and deployment needs across all supported platforms.