CI/CD Pipeline

Relevant source files

• .github/workflows/rust-lint.yml
• .github/workflows/rust-tests.yml
• .gitignore
• CHANGELOG.md
• simd-r-drive-entry-handle/src/debug_assert_aligned.rs

Purpose and Scope

This document describes the Continuous Integration and Continuous Deployment (CI/CD) infrastructure for the SIMD R Drive project. It covers the GitHub Actions workflows that enforce code quality, run automated tests, and validate security compliance. The CI/CD system ensures that all code changes meet quality standards before being merged.

For information about building and running tests locally, see Building and Testing. For version-specific breaking changes and migration strategies, see Version History and Migration.

CI/CD Architecture Overview

The SIMD R Drive project uses two primary GitHub Actions workflows to validate all code changes:

Diagram: CI/CD Workflow Architecture

graph TB
    subgraph "Trigger Events"
        Push["Push to main"]
PR["Pull Request"]
Tag["Tag push (v*)"]
end
    
    subgraph "rust-tests.yml"
        TestMatrix["Matrix Testing"]
BuildStep["cargo build"]
TestStep["cargo test"]
BenchCheck["cargo bench --no-run"]
Cache["Cargo Cache"]
end
    
    subgraph "rust-lint.yml"
        FmtCheck["cargo fmt --check"]
ClippyCheck["cargo clippy"]
DocCheck["cargo doc"]
DenyCheck["cargo-deny check"]
AuditCheck["cargo-audit"]
end
    
 
   Push --> TestMatrix
 
   Push --> FmtCheck
 
   PR --> TestMatrix
 
   PR --> FmtCheck
 
   Tag --> TestMatrix
    
 
   TestMatrix --> Cache
 
   Cache --> BuildStep
 
   BuildStep --> TestStep
 
   TestStep --> BenchCheck
    
 
   FmtCheck --> ClippyCheck
 
   ClippyCheck --> DocCheck
 
   DocCheck --> DenyCheck
 
   DenyCheck --> AuditCheck
    
    style TestMatrix fill:#f9f9f9
    style FmtCheck fill:#f9f9f9

The system runs two independent workflows in parallel. The rust-tests.yml workflow performs functional validation through matrix testing across multiple platforms and feature configurations. The rust-lint.yml workflow enforces code quality standards, documentation completeness, and security compliance. All checks must pass before a pull request can be merged.

Sources: .github/workflows/rust-tests.yml:1-62 .github/workflows/rust-lint.yml:1-44

Test Workflow (rust-tests.yml)

Workflow Configuration

The test workflow executes on three trigger events:

Sources: .github/workflows/rust-tests.yml:3-8

Matrix Testing Strategy

The workflow uses a comprehensive matrix strategy to test across multiple dimensions:

Diagram: Matrix Testing Dimensions

graph TB
    subgraph "Operating Systems"
        Ubuntu["ubuntu-latest"]
MacOS["macos-latest"]
Windows["windows-latest"]
end
    
    subgraph "Feature Configurations"
        Default["Default\nflags: (empty)"]
NoDefault["No Default Features\nflags: --no-default-features"]
Parallel["Parallel\nflags: --features parallel"]
ExposeAPI["Expose Internal API\nflags: --features expose-internal-api"]
ParallelAPI["Parallel + Expose API\nflags: --features=parallel,expose-internal-api"]
AllFeatures["All Features\nflags: --all-features"]
end
    
    subgraph "Test Job Matrix"
        Job["test job\nOS x Features\n3 x 6 = 18 configurations"]
end
    
 
   Ubuntu --> Job
 
   MacOS --> Job
 
   Windows --> Job
    
 
   Default --> Job
 
   NoDefault --> Job
 
   Parallel --> Job
 
   ExposeAPI --> Job
 
   ParallelAPI --> Job
 
   AllFeatures --> Job

Each job runs the complete build-test-benchmark pipeline with a unique combination of operating system and feature flags, resulting in 18 total test configurations per workflow execution.

Sources: .github/workflows/rust-tests.yml:13-30

Test Job Steps

Each matrix job executes the following steps:

1. Repository Checkout

Sources: .github/workflows/rust-tests.yml:33-34

2. Rust Toolchain Installation

Uses the stable Rust toolchain across all platforms.

Sources: .github/workflows/rust-tests.yml:36-37

3. Dependency Caching

The workflow caches Cargo dependencies to reduce build times:

The cache key includes the OS, Cargo.lock hash, and matrix flags to ensure correct cache isolation between configurations.

Sources: .github/workflows/rust-tests.yml:40-52

4. Build Step

Builds all workspace crates with all targets (library, binaries, tests, benches, examples) using the matrix-specified feature flags.

Sources: .github/workflows/rust-tests.yml:54-55

5. Test Execution

Runs all tests in the workspace with verbose output, including:

• Unit tests
• Integration tests
• Documentation tests
• Example tests

Sources: .github/workflows/rust-tests.yml:57-58

6. Benchmark Compilation Check

Validates that all benchmarks compile successfully without executing them. The --no-run flag ensures benchmarks are compiled but not executed in CI.

Sources: .github/workflows/rust-tests.yml:60-62

Matrix Configuration Table

Sources: .github/workflows/rust-tests.yml:14-30

Lint Workflow (rust-lint.yml)

Workflow Configuration

The lint workflow runs on all pushes and pull requests without branch restrictions:

Sources: .github/workflows/rust-lint.yml3

Lint Job Architecture

Diagram: Lint Workflow Execution Pipeline

The lint workflow enforces five quality gates in sequence, with each step dependent on the previous step's success.

Sources: .github/workflows/rust-lint.yml:5-44

Quality Gate 1: Code Formatting

Validates that all Rust code adheres to the standard formatting rules defined by rustfmt. The --check flag ensures the command fails if any files require formatting without modifying them.

Sources: .github/workflows/rust-lint.yml:26-27

Quality Gate 2: Clippy Linting

Runs Clippy across the entire workspace with maximum coverage:

• --workspace: Checks all workspace crates
• --all-targets: Includes lib, bins, tests, benches, examples
• --all-features: Enables all optional features
• -D warnings: Treats all warnings as errors

Sources: .github/workflows/rust-lint.yml:29-31

Quality Gate 3: Documentation Validation

Generates documentation and fails on any documentation warnings:

• RUSTDOCFLAGS="-D warnings": Treats doc warnings as errors
• --no-deps: Only documents workspace crates, not dependencies
• --document-private-items: Includes private items to ensure complete internal documentation

Sources: .github/workflows/rust-lint.yml:33-35

Quality Gate 4: Dependency Security Check

Runs cargo-deny to validate dependency security and licensing:

• Checks for security advisories in dependencies
• Validates license compatibility
• Detects duplicate dependencies
• Enforces allowed/denied crate policies

The tool requires prior installation via cargo install cargo-deny.

Sources: .github/workflows/rust-lint.yml:20-22 .github/workflows/rust-lint.yml:37-39

Quality Gate 5: Vulnerability Audit

Scans Cargo.lock for known security vulnerabilities in dependencies by checking against the RustSec Advisory Database. Requires prior installation via cargo install cargo-audit.

Sources: .github/workflows/rust-lint.yml:20-23 .github/workflows/rust-lint.yml:41-43

Component Installation Workaround

The workflow includes a workaround for a GitHub Actions environment issue:

This step explicitly installs rustfmt and clippy components to address a toolchain installation issue where these components may not be available by default.

Sources: .github/workflows/rust-lint.yml:13-18

Quality Gates Summary

The complete CI/CD pipeline enforces the following quality gates:

All quality gates must pass for the CI/CD pipeline to succeed. The matrix testing strategy in rust-tests.yml ensures compatibility across three operating systems and six feature configurations, providing comprehensive validation coverage.

Sources: .github/workflows/rust-tests.yml:54-62 .github/workflows/rust-lint.yml:26-43

Workflow Execution Context

Runner Configuration

Both workflows execute on GitHub-hosted runners:

Sources: .github/workflows/rust-tests.yml13 .github/workflows/rust-lint.yml7

Fail-Fast Strategy

The test workflow uses fail-fast: false to allow all matrix jobs to complete even if one fails, providing comprehensive failure information:

This configuration is valuable for identifying platform-specific or feature-specific issues across the entire matrix rather than stopping at the first failure.

Sources: .github/workflows/rust-tests.yml15

graph LR
    LocalDev["Local Development"]
Commit["git commit"]
Push["git push"]
PR["Pull Request"]
TestsCI["rust-tests.yml\n18 matrix jobs"]
LintCI["rust-lint.yml\n5 quality gates"]
Merge["Merge to main"]
Tag["Tag release (v*)"]
LocalDev --> Commit
 
   Commit --> Push
 
   Push --> PR
    
 
   PR --> TestsCI
 
   PR --> LintCI
    
 
   TestsCI -->|Pass| Merge
 
   LintCI -->|Pass| Merge
    
 
   Merge --> Tag
 
   Tag --> TestsCI

Integration with Development Workflow

The CI/CD pipeline integrates with the development workflow at multiple points:

Diagram: CI/CD Integration Points

The CI/CD system provides automated validation at multiple stages of the development lifecycle. Pull requests trigger both workflows, ensuring all quality gates pass before code review. Pushes to main and version tags also trigger the test workflow to validate the stability of the main branch and release candidates.

Sources: .github/workflows/rust-tests.yml:3-8 .github/workflows/rust-lint.yml3

Related CI/CD Artifacts

Ignored Paths

The repository excludes certain paths from version control that are relevant to CI/CD execution:

These exclusions prevent CI cache pollution and ensure consistent builds across environments.

Sources: .gitignore:1-11

Debug Assertions in CI

The codebase includes conditional debug assertions that activate during CI test runs:

The debug_assert_aligned and debug_assert_aligned_offset functions in simd-r-drive-entry-handle/src/debug_assert_aligned.rs:26-88 activate only when cfg(any(test, debug_assertions)) is true. In CI test runs, these assertions validate alignment invariants for memory-mapped payloads and zero-copy access patterns without impacting release builds or benchmarks.

Sources: simd-r-drive-entry-handle/src/debug_assert_aligned.rs:1-88

Maintenance and Evolution

The CI/CD pipeline configuration is versioned alongside the codebase and evolves with project requirements. Changes to the pipeline typically correspond to:

• New feature flags requiring matrix coverage
• Additional security tools or quality gates
• Platform support changes
• Performance optimization validation

Historical changes to the CI/CD infrastructure can be tracked through the repository's commit history in the .github/workflows/ directory.

For information about breaking changes that may affect CI/CD behavior, see Version History and Migration, particularly the alignment changes in version 0.15.0 that introduced new debug assertions.

Sources: CHANGELOG.md:25-51