CI/CD Pipelines Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Numan Registry utilizes a robust CI/CD architecture designed for a data-only repository. Its primary purpose is to maintain the integrity and security of the signed Numan registry index (index.json). The system transitions through stages of validation, from local preflight checks to protected production deployment, ensuring that only verified, cryptographically signed metadata reaches the public CDN hosted on GitHub Pages.
Sources: README.md:1-10, AGENTS.md:7-12, SECURITY.md:1-5
Pipeline Architecture and Environments
The project defines three distinct execution environments for its workflows, each with varying levels of sensitivity and permission. All workflows default to permissions: contents: read to maintain a secure baseline.
| Environment | Purpose | Key Characteristics |
|---|---|---|
| Build Validation | PR safety checks | Runs secret scans, preflight checks, and schema validation. No production secrets. |
| Staging | Staging publication | Deploys index using ephemeral CI keys to assert non-production trust. |
| Production | Official publication | Protected environment. Accesses NUMAN_REGISTRY_PRIVATE_KEY for official signing. |
Sources: README.md:94-105, scripts/test_workflow_safety.py:53-56
Workflow Flow Diagram
The following diagram illustrates the progression from code submission to production publication.
Core CI Check Components
The CI/CD pipeline executes a specific toolchain located in the scripts/ directory. These tools ensure schema compliance, cryptographic validity, and repository safety invariants.
1. Static and Structural Validation
- Secret Scanner (
scan_for_secrets.py): Scans git-tracked files for private-key material (*.key,*.pem). - Preflight (
preflight.py): Checks for key and workflow consistency without requiring network access or secrets. - Schema Validator (
validate.py): Checksindex.jsonagainstschemas/index-v1.jsonand verifies detached Ed25519 signatures. - Parser Check (
numan-parser-check): A Rust-based check that uses the production Numan registry parser to ensure parity between tooling and the actual client.
Sources: AGENTS.md:15-26, REVIEW.md:5-20, README.md:118-121
2. Intake Validation Harness
The scripts/validate_candidate.py script orchestrates a multi-stage validation process for new package specifications.
Security and Trust Invariants
The CI/CD pipeline enforces several critical trust invariants to prevent unauthorized publication or registry corruption.
- Credential Masking: Signing values are passed as data objects, not shell templates, to prevent injection vulnerabilities.
- Protected Environment: The
production.ymlworkflow is the only place wheresecrets.NUMAN_REGISTRY_PRIVATE_KEYis exposed. It requiresneeds: validateto ensure all checks pass before the secret is accessed. - Action Pinning: Every GitHub Action used in the workflows is pinned to a 40-character commit SHA to prevent supply-chain attacks via tag updates.
- Immutability: Remediation for malicious artifacts is always a new signed index revision (yank or new version), never an in-place rewrite of existing bytes.
Sources: scripts/test_workflow_safety.py:38-45, scripts/test_workflow_safety.py:77-85, SECURITY.md:54-58, REVIEW.md:30-40
Package Promotion Workflow
Promoting a package to the production registry requires successful "Stage 1" evidence. This is handled via scripts/lifecycle-prove.py, which proves a package on a clean root with a real Nu binary matching the package's version constraints. CI-built plugins from the numan-plugins repository are further linted by scripts/lint-manifest-index.py to ensure version ranges match.
Sources: README.md:123-138, AGENTS.md:27-30, REVIEW.md:43-50
The Numan Registry CI/CD pipeline prioritizes security through a "verify-then-sign" architecture. By isolating production secrets in a protected environment and enforcing strict schema and parser parity checks in every PR, the system ensures the official catalog remains a trusted source for Nushell package management.