CI/CD & Releasing
Relevant source files
The following files were used as context for generating this wiki page:
The CI/CD and releasing systems in Numan are designed to ensure cross-platform stability across Linux, macOS, and Windows. The project employs a multi-tiered validation approach, ranging from unit tests to "real-Nu" acceptance tests that execute against actual Nushell binaries. Releasing is managed through version tags, automated GitHub Actions workflows, and cross-repository contract pinning to maintain synchronization between Numan and its sibling projects.
Sources: CONTRIBUTING.md:27-28, AGENTS.md:14-22, README.md:19-21
Continuous Integration Gates
Every pull request and commit to the master branch must pass a standardized suite of automated quality gates. These gates enforce code style, functional correctness, and security invariants.
Quality Gate Components
| Component | Tool / Command | Purpose |
|---|---|---|
| Linting | cargo clippy -- -D warnings | Enforces idiomatic Rust and catches common errors. |
| Formatting | cargo fmt --check | Ensures consistent code style across the project. |
| Unit Testing | cargo test | Executes the full internal test suite (approx. 419 tests). |
| Acceptance | cargo test -- --ignored | Runs "real-Nu" integration tests requiring a nu binary on PATH. |
| MSRV | rust-version = "1.88" | Enforces Minimum Supported Rust Version. |
Sources: CONTRIBUTING.md:17-21, AGENTS.md:14-22, CHANGELOG.md:104-107
Multi-Platform Coverage
CI workflows are executed on three primary operating systems to ensure the cross-platform nature of the package manager:
- Ubuntu (Linux)
- Windows
- macOS
Sources: CONTRIBUTING.md:27-28, AGENTS.md:14-22
Release Management and Distribution
Numan follows Semantic Versioning for all releases. The release process involves building optimized binaries for multiple targets and distributing them through several channels.
Build Targets
| Platform | Archive Format | Binary Name |
|---|---|---|
| Linux (x86_64) | .tar.gz | numan |
| Windows (x86_64) | .zip | numan.exe |
| macOS (Apple Silicon) | .tar.gz | numan |
| macOS (Intel) | .tar.gz | numan |
Sources: README.md:126-132, CHANGELOG.md:83-84
Distribution Channels
- GitHub Releases: The primary source for pre-built binaries and
SHA256SUMSverification files. - Crates.io: Available as the
numan-clicrate for source-based installation viacargo install. - WinGet: Automated publication to the Windows Package Manager using the
tonythethompson.numanidentifier.
Sources: README.md:149-163, CHANGELOG.md:112-113
Cross-Repository Coordination
Numan's ecosystem spans three repositories: numan, numan-plugins, and numan-registry. To prevent "roadmap drift" where one repository implements features not yet supported by others, the project uses a "Roadmap Contract" system.
The Roadmap Contract
The contract is a versioned Git tag in the main numan repository that freezes the consolidated roadmap and drift-checking scripts.
This diagram shows how the contract tag in the primary Numan repository acts as the source of truth for CI workflows in sibling repositories.
Sources: cross-repo-mirror/README.md:5-17, scripts/bump-contract.sh:5-15
Contract Bumping Process
The scripts/bump-contract.sh utility orchestrates coordinated changes across all three repositories. It ensures that sibling repositories are pinned to a specific commit SHA of the contract to prevent silent drift caused by force-pushes.
- Local Validation: Runs
check-roadmap-drift.pyagainst the local roadmap. - Tag Creation: Mints a new annotated contract tag (e.g.,
numan-roadmap-contract/v2). - Pin Rewriting: Updates
CONTRACT_TAGandCONTRACT_SHAin CI YAML files. - PR Generation: Uses the
ghCLI to open synchronized pull requests in all three repositories.
Sources: scripts/bump-contract.sh:30-58, cross-repo-mirror/README.md:22-35
Trust Root Maintenance
The "Official Registry" trust root is hardcoded into the binary for production security. This Ed25519 public key is managed via scripts/update-official-trust-root.sh.
Key Rotation Workflow
This sequence illustrates the secure update path for the built-in trust root used to verify registry indexes.
Sources: scripts/update-official-trust-root.sh:10-30, AGENTS.md:115-116
Summary
The CI/CD and Releasing infrastructure in Numan prioritizes immutability and reproducibility. By enforcing strict CI gates across three OS targets and using a multi-repo contract system, Numan ensures that its core promise—that installs remain inert and safe until explicit activation—is maintained across all supported environments and ecosystem components.