CI/CD & Prebuilt Artifacts
Relevant source files
The following files were used as context for generating this wiki page:
cargo-cooldown provides a robust infrastructure for Continuous Integration (CI) environments through the provision of prebuilt binaries and specialized non-interactive execution modes. The system is designed to allow rapid adoption in automated pipelines without requiring a full compilation of the tool from source, while maintaining high security standards through provenance verification.
The project differentiates between local development workflows and CI/CD pipelines. While local workflows often involve interactive setup and immediate building, CI/CD integrations focus on using pre-existing Cargo.lock files and non-interactive enforcement of cooldown windows to protect the supply chain during automated builds and testing.
Sources: README.md:12-19, README.md:121-124
Artifact Distribution and Verification
Prebuilt artifacts are distributed as GitHub Release assets, specifically optimized for use with cargo-binstall. This allows CI runners to acquire the binary quickly without the overhead of a full Rust build.
Provenance and Security
To ensure the integrity of the supply chain, every release includes SHA256SUMS and GitHub Artifact Attestations. Users can verify that a specific binary was produced by the official repository using the GitHub CLI (gh).
Sources: README.md:21-31
gh attestation verify cargo-cooldown-x86_64-unknown-linux-gnu-vX.Y.Z.tgz \
-R dertin/cargo-cooldown
Sources: README.md:28-29
Binstall Configuration
The Cargo.toml manifest defines specialized metadata to facilitate the cargo-binstall process, specifying URL patterns for releases and platform-specific overrides (e.g., using .zip for Windows and .tgz for other platforms).
Sources: Cargo.toml:13-21
| Property | Value/Format | Description |
|---|---|---|
pkg-url | {repo}/releases/download/v{version}/{name}-{target}-v{version}{archive-suffix} | The template for downloading the artifact |
bin-dir | {name}-{target}-v{version}/{bin}{binary-ext} | The path to the binary within the archive |
pkg-fmt | tgz (Default), zip (Windows) | The archive format used for distribution |
| Sources: Cargo.toml:14-21 |
Automated Integration Strategies
cargo-cooldown supports automation through environment variables and non-interactive CLI flags. This is essential for CI scripts that cannot handle the interactive prompts of the init wizard or the cargo_compatible enforcement mode.
Non-Interactive Enforcement
In CI environments, the cargo_compatible enforcement mode usually requires a prompt if fresh versions are detected. To bypass this for automation, the COOLDOWN_CARGO_COMPATIBLE_ACCEPT environment variable can be set to auto.
Sources: src/executor.rs:245-251, src/executor.rs:271-274
The flow above illustrates how cargo-cooldown handles fresh version detection in automated contexts.
Sources: src/executor.rs:232-255, src/executor.rs:271-290
Workspace and Project Initialization
For CI pipelines that initialize new environments, cargo-cooldown provides a non-interactive setup path. While cargo cooldown init is primarily a wizard, the resulting cooldown.toml can be pre-generated or configured via environment variables, which take precedence over file-based configuration.
Sources: src/init.rs:36-70, README.md:65-70
Testing and Benchmarking in CI
The project includes specialized scripts and test harnesses designed for CI validation, ensuring the cooldown logic remains accurate across different registry states.
Integration Test Harness
The TestHarness structure in the integration suite allows for deterministic testing by mocking registry responses and simulating different "publish times" for crates. This allows CI to verify that the tool correctly identifies and cools "fresh" crates without depending on the live crates.io state.
Sources: tests/integration.rs:592-620
Performance Benchmarking
CI pipelines can utilize the run-crates-io-benchmark.sh script to measure the "wall-clock" performance of the cooldown resolver. Key metrics tracked include:
- Average Duration: Total time taken for the cooldown pass.
- HTTP Fallback Usage: Number of times the tool had to hit the Registry API because local index
pubtimewas missing. - Artifact Preservation: Storage of measured
Cargo.lockartifacts for regression analysis.
Sources: examples/run-crates-io-benchmark.sh:310-336, examples/README.md:1-12
Environment Configuration for Automation
The benchmarking and smoke test scripts demonstrate how to configure cargo-cooldown for CI via environment variables:
Sources: examples/run-crates-io-benchmark.sh:11-20, examples/run-crates-io-smoke.sh:100-115
| Variable | Recommended CI Value | Purpose |
|---|---|---|
COOLDOWN_ENFORCEMENT | strict or cargo_compatible | Defines the failure policy for fresh crates. |
COOLDOWN_CARGO_COMPATIBLE_ACCEPT | auto | Ensures non-interactive execution in compatible mode. |
COOLDOWN_VERBOSE | 1 | Enables detailed logging for debugging CI failures. |
CARGO_TERM_PROGRESS_WHEN | never | Disables interactive progress bars in CI logs. |
| Sources: examples/run-crates-io-benchmark.sh:11-20, examples/run-crates-io-smoke.sh:100-115 |
cargo-cooldown is engineered to be a "drop-in" security layer for Rust CI/CD pipelines, providing verifiable binaries and flexible, non-interactive enforcement policies to mitigate supply chain risks at the point of build.
Sources: README.md:1-10, README.md:121-124