Production Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Production deployment for the Numan Official Registry involves the secure signing and publication of a curated JSON index to GitHub Pages. Because this is a data-only repository, the "application" consists of a signed registry index and a supporting Python toolchain. The deployment process is designed to prevent private-key exposure and ensure that only human-reviewed, cryptographically verified metadata reaches production clients.
The system enforces a strict separation between build validation and the signing job. Production signing only occurs within a protected GitHub Environment, requiring manual dispatch and specific reviewer approval. This ensures that the official trust root baked into the Numan CLI remains secure.
Sources: README.md:1-20, AGENTS.md:7-10, SECURITY.md:55-65
Deployment Architecture
The deployment architecture follows a multi-stage validation and signing flow. The production index is canonicalized and signed using an Ed25519 private key, which is stored as a protected GitHub secret and never committed to the repository.
Signing Workflow Flowchart
The following diagram illustrates the transition from a proposed change to a signed production artifact.
The diagram shows the logic gate between staging (ephemeral) and production (protected) environments.
Sources: README.md:90-105, REVIEW.md:28-40, scripts/test_workflow_safety.py:45-60
Security and Trust Root
The production registry is anchored by the official trust root. Security is maintained through strict key management and detached signatures.
Key Management Requirements
The production private key (NUMAN_REGISTRY_PRIVATE_KEY) is never handled by coding agents or committed to the source tree. It is provisioned locally via a dedicated script and stored in an encrypted vault.
| Component | Responsibility | Source File |
|---|---|---|
| Private Key | Never committed; stored in GitHub Environment secrets. | README.md:80 |
| Public Key | Committed to keys/official.pub. | README.md:43 |
| Signature | Detached JSON envelope in registry/index.json.sig. | README.md:52 |
| Placeholder | Source-tree signature is a PLACEHOLDER by design. | AGENTS.md:39 |
Sources: README.md:43-52, AGENTS.md:39-43, scripts/provision-production-key.sh:130-150
Detached Signature Envelope
The signing process produces a detached signature in the following JSON format:
{
"key_id": "official-YYYY-MM",
"algorithm": "ed25519",
"signature": "base64..."
}
Sources: README.md:70-76
Continuous Integration Gates
Before any deployment, the toolchain enforces a set of "Repo Safety" gates. These scripts ensure index integrity, secret avoidance, and parser compatibility.
CI Sequence Diagram
This diagram shows the interactions between the CI scripts and the registry artifacts during a validation run.
The sequence demonstrates the layered validation approach used in both staging and production.
Sources: AGENTS.md:16-30, REVIEW.md:7-20, scripts/test_workflow_safety.py:58-65
Production Provisioning
Maintainers use scripts/provision-production-key.sh to generate key material. The script is designed for safety, ensuring private keys are never printed to the terminal.
Provisioning Steps
- Generation: Run
./scripts/provision-production-key.shin a secure environment (WSL recommended). - Secret Storage: Copy the resulting
.keyfile into the GitHub "production" environment secretNUMAN_REGISTRY_PRIVATE_KEY. - Public Key Update: Commit the
.pubfile content tokeys/official.pub. - Client Update: Update the Numan CLI trust root with the matching
key_idand public key.
Sources: scripts/provision-production-key.sh:10-30, README.md:80-88
Deployment Environments
The project defines three distinct environments for registry management:
- Build Validation: Runs on every PR; has read-only permissions and no access to production secrets.
- Staging: Signs the
mainbranch with an ephemeral CI key to verify the publication path without asserting production trust. - Production Signing: A manual dispatch workflow. It only exposes the production signing key to the
sign-and-publishjob after a successful, separate, read-only validation job.
Sources: README.md:95-108, scripts/test_workflow_safety.py:46-55
Conclusion
The Production Deployment system for Numan Registry prioritizes cryptographic integrity over automated speed. By using detached Ed25519 signatures, protected GitHub environments, and a multi-stage validation toolchain, the project ensures that Nushell users can trust the curated catalog without risk of secret leakage or automated index corruption.
Sources: SECURITY.md:55-65, REVIEW.md:42-50