CI/CD and Release Process
Relevant source files
The following files were used as context for generating this wiki page:The CI/CD and release process for caro is a comprehensive system designed to ensure code quality, security, and cross-platform reliability. It leverages GitHub Actions for automation, with a strong emphasis on Test-Driven Development (TDD), security auditing, and consistent local testing. The process covers continuous integration, publishing to registries, and creating versioned releases with platform-specific binaries.
The core of the local testing process is the test-ci-locally.sh script, which mirrors the automated GitHub Actions workflows, giving developers high confidence that their changes will pass CI before pushing. The entire system is built around a "safety-first" principle, with security checks integrated at multiple stages.
Sources: test-ci-locally.sh, specs/001-create-a-comprehensive/tasks.md:4, CONTRIBUTING.md:155-162
Continuous Integration (CI) Workflow
The primary CI workflow is defined in .github/workflows/ci.yml and is mirrored by the test-ci-locally.sh script. It runs on every pull request and push to the main branch, executing a series of checks across multiple platforms (macOS, Linux, Windows).
Sources: test-ci-locally.sh:8, specs/001-create-a-comprehensive/tasks.md:4, exports/session-logs/2025-10-01-check-the-pr.txt:71-78
CI Workflow Diagram
This diagram shows the sequence of jobs executed in the main CI workflow.
Sources: test-ci-locally.sh:80-227
CI Jobs
The CI pipeline is composed of several distinct jobs that validate different aspects of the codebase.
| Job | Description | Source File |
|---|---|---|
| Check Formatting | Ensures all code adheres to rustfmt standards. | test-ci-locally.sh:81-84 |
| Run Clippy | Runs the Rust linter to catch common mistakes and enforce idioms, with all warnings treated as errors. | test-ci-locally.sh:86-89 |
| Comprehensive Tests | Runs the entire test suite (cargo test --workspace) in a single-threaded mode to ensure all tests pass. | test-ci-locally.sh:91-94 |
| MLX Backend Tests | Platform-specific tests for the MLX backend, which run only on macOS Apple Silicon (aarch64). | test-ci-locally.sh:96-106 |
| E2E & Integration Tests | A suite of end-to-end, integration, and contract tests run per platform. | test-ci-locally.sh:108-158 |
| Security Audit | Runs cargo audit to check for dependencies with known security vulnerabilities. | test-ci-locally.sh:160-170 |
| Build Release Binary | Compiles the project in release mode with platform-specific features. | test-ci-locally.sh:172-184 |
| Performance Benchmarks | Runs benchmarks and checks that the final binary size is within the 50MB limit. | test-ci-locally.sh:186-211 |
| Code Coverage | (Optional) Generates a code coverage report using cargo-llvm-cov if installed. | test-ci-locally.sh:213-221 |
Sources: test-ci-locally.sh, specs/001-create-a-comprehensive/tasks.md:5
Local CI Testing
To ensure CI will pass before pushing to GitHub, developers must use the test-ci-locally.sh script. This script executes all the jobs defined in the GitHub Actions workflows.
#!/bin/bash
#
# test-ci-locally.sh
#
# Comprehensive local CI testing script that mirrors all GitHub Actions workflows
# Ensures 100% confidence that CI will pass before pushing to GitHub
#
# Workflows tested:
# 1. CI (ci.yml) - Test suite, formatting, linting, builds, benchmarks, coverage
# 2. Release (release.yml) - Release testing workflow (triggered after publish)
# 3. Publish (publish.yml) - Publish workflow tests
#
set -euo pipefail
Sources: test-ci-locally.sh:1-14
The script provides detailed logging and a final summary of passed, failed, and skipped tests.
Sources: test-ci-locally.sh:265-293
Pull Request & Merging Process
The project follows a strict Pull Request (PR) based development model. All changes, including those from maintainers, must go through a PR and receive at least one approval.
Sources: CONTRIBUTING.md:165-168
PR Lifecycle
The following diagram illustrates the process from creating a PR to merging it.
Key aspects of the process include:
- TDD Foundation: PRs are expected to follow Test-Driven Development, often submitting failing tests first as a contract.
- Automated Checks: The CI workflow runs automatically, checking for formatting, linting, test compilation, and security vulnerabilities.
- Squash and Merge: The preferred merge strategy is "Squash and Merge" to maintain a clean
mainbranch history. This is done via theghCLI.
Sources: exports/session-logs/2025-10-01-check-the-pr.txt:294-298, CONTRIBUTING.md:188-191
Release and Publish Workflow
The project has distinct workflows for publishing to a package registry and creating a GitHub Release. These are defined in .github/workflows/publish.yml and .github/workflows/release.yml respectively.
Sources: test-ci-locally.sh:10-12
Publish Workflow
This workflow prepares the crate for publishing. It focuses on verification and packaging.
- Verify Version Consistency: Checks that the version in
Cargo.tomlis consistent. - Verify Test Compilation: Ensures all tests, including platform-specific ones like MLX, compile successfully.
- Verify Package Creation: Runs
cargo package --allow-dirtyto ensure the crate can be packaged without errors.
Sources: test-ci-locally.sh:226-241
Release Workflow
The release process involves building binaries for multiple platforms, creating installers, and publishing them to GitHub Releases.
This diagram outlines the steps for creating a new release.
Release Artifacts
The release workflow generates platform-specific binaries and installers.
| Platform | Target | Features | Installer |
|---|---|---|---|
| macOS (Apple Silicon) | aarch64-apple-darwin | mlx, embedded | .dmg |
| macOS (Intel) | x86_64-apple-darwin | candle, embedded | .dmg |
| Linux | x86_64-unknown-linux-gnu | candle, embedded | .tar.gz |
| Windows | x86_64-pc-windows-msvc | candle, embedded | .msi |
The release process is automated using the gh CLI to create the release, upload assets, and publish release notes.
Sources: specs/004-implement-ollama-and/tasks.md:329-373, exports/session-logs/2025-09-13-readme.txt:200-208
Summary
The caro project's CI/CD and release process is a robust, automated system designed to enforce high standards of quality and security. By integrating local testing scripts that mirror the CI environment, it empowers developers to contribute with confidence. The multi-platform build and release strategy ensures that caro is accessible to users on macOS, Linux, and Windows, with optimizations for specific hardware like Apple Silicon. The entire process, from PR to release, is transparent and follows modern open-source best practices.