Staging Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Staging Environment serves as the intermediate validation tier for the Numan Official Registry. It is designed to exercise the full sign-to-verify path using ephemeral credentials before any changes are promoted to the production trust root. The staging workflow ensures that the index.json catalog remains schema-valid and technically sound without exposing the production NUMAN_REGISTRY_PRIVATE_KEY.
Sources: README.md:104-107, AGENTS.md:38-41
In this environment, the default branch is signed with an ephemeral CI key. While staging validates the integrity of the registry and its signature logic, it explicitly does not assert production trust. This separation allows for high-fidelity testing of the deployment pipeline while maintaining the security of the official trust root.
Sources: README.md:104-107, REVIEW.md:58-59
CI/CD Workflow Architecture
The staging environment is governed by the .github/workflows/staging.yml workflow. This workflow is triggered on changes to the default branch and consists of two primary stages: a read-only validation job and a publication job.
Sources: README.md:91-95, scripts/test_workflow_safety.py:65-69
Validation and Signing Flow
The staging workflow mirrors the production signing path but utilizes temporary keys generated during the CI run. This allows the system to verify that the scripts/ci-sign.py and scripts/validate.py tools function correctly in a live environment.
The diagram shows the progression from a code push to the deployment of a signed staging artifact.
Sources: README.md:91-95, AGENTS.md:38-41, scripts/test_workflow_safety.py:65-69
Environmental Constraints
To maintain security, the staging environment operates under strict permission boundaries. The initial validation steps are performed in a read-only context, and write permissions are only granted to the specific publication job.
| Feature | Staging Implementation |
|---|---|
| Signing Key | Ephemeral Ed25519 (generated per run) |
| Permissions | contents: read (Initial), contents: write (Publish only) |
| Trust Assertion | None (Does not assert production trust) |
| Signature Target | Canonical JSON bytes of index.json |
Sources: README.md:104-107, scripts/test_workflow_safety.py:65-69
Staging Validation Logic
Staging utilizes the same validation suite as the production environment but with configurations that allow for the testing of provisional entries.
Validation Commands
Maintainers and CI use scripts/validate.py to check the staging index. In staging, the --allow-provisional-lifecycle flag is often employed to permit packages that have not yet completed the mandatory Stage 1 lifecycle-prove evidence required for production.
Sources: scripts/validate_candidate.py:127-133, scripts/test_workflow_safety.py:82-84
This sequence illustrates the signature generation and verification loop within the staging environment.
Sources: AGENTS.md:38-41, README.md:82-89
Handling the Placeholder Signature
In the source tree, registry/index.json.sig contains a PLACEHOLDER value. The staging environment intentionally overwrites this locally during the CI process to verify signing, but the committed placeholder must never be treated as a valid signature for production use.
Sources: REVIEW.md:35-37, AGENTS.md:33-36
Provisioning and Testing
To exercise the staging path locally, developers are instructed to generate temporary Ed25519 keypairs and utilize the CI signing scripts. This prevents accidental corruption of the production keys/official.pub or the placeholder signature in the registry/ directory.
Local Staging Simulation
# Example simulation of the staging signing path
python3 scripts/ci-sign.py --key-id staging-test --key "$PRIVATE_KEY" --index registry/index.json --out temp.sig
python3 scripts/validate.py --index registry/index.json --sig temp.sig --pub temp.pub
Sources: AGENTS.md:38-41, scripts/ci-sign.py
Maintenance Gates
Staging serves as the gate for Stage 2 requirements, such as ensuring that an active[] plugin's nu_version in the manifest agrees with the owner/name/version in the index.
Sources: AGENTS.md:27-31, REVIEW.md:27-29
The Staging Environment is a critical component of the Numan Registry's reliability, providing a safe space to verify the integrity of the signing toolchain and the catalog schema before final production deployment. By using ephemeral keys, it ensures that the trust logic is fully tested without risking the production environment's security.
Sources: README.md:104-107, AGENTS.md:38-41