Repository Safety Checks
Relevant source files
The following files were used as context for generating this wiki page:
Repository Safety Checks constitute the CI/CD gating and architectural invariants designed to ensure the integrity, immutability, and security of the numan-plugins binary delivery pipeline. The primary purpose of these checks is to maintain a strict trust boundary where this repository builds and hosts binaries without ever possessing signing keys, ensuring that all published artifacts are traceable to immutable upstream commits.
These safety mechanisms are enforced through automated GitHub Actions workflows (e.g., repo-safety.yml), unit tests, and specialized Python scripts that validate the build manifest, verify upstream tag provenance, and manage release transactions.
Sources: README.md:21-29, REVIEW.md:7-12, scripts/test_workflow_safety.py:12-16
Architectural Invariants and CI Gates
The project adheres to several P0-level safety invariants that must be verified during every pull request and automated review. These invariants prevent trust-boundary breaks and ensure that the repository remains a "feeder" for the official registry rather than a signing authority.
Key Safety Invariants
- Builds Only, Never Signs: This repository hosts binaries; Ed25519 signing material stays in
numan-registry. - No Private Keys: Signing keys, PEM material, or registry secrets are strictly prohibited.
- Immutable Upstream Pins: All
active[]entries inmanifest.jsonmust pin human-facing tags to immutablesource_commitSHAs. - Draft-then-Finalize: New releases are assembled as run-owned drafts and only made public after the complete asset set is verified.
- Manual Publish Only: The
build-pluginsworkflow only publishes when manually dispatched with a non-emptyonly=package list; PR and push paths are restricted to validation.
Sources: REVIEW.md:14-35, README.md:21-29
CI Gate Verification Flow
The following diagram illustrates the automated checks required for every pull request to pass the repository safety gate.
Manifest and Provenance Validation
The manifest.json file serves as the source of truth for all "active" plugins. Safety checks ensure that every plugin defined in the manifest is correctly configured and maps to an authentic upstream source.
Manifest Integrity Checks
The validate_manifest.py script enforces strict schema requirements for every entry in the active[] list.
| Field | Requirement | Purpose |
|---|---|---|
source_commit | 40-character hex SHA | Ensures immutable provenance of the source code. |
tag | String | Human-facing versioning associated with the commit. |
nu_version | Semver range | Compatibility check against Nushell versions. |
repo | owner/repo format | Points to the original plugin repository. |
Sources: scripts/validate_manifest.py:16-29, manifest.json:8-20
Upstream Tag Resolution
To prevent "tag floating" or supply-chain attacks, the system verifies that the human-facing tag in the manifest actually resolves to the pinned source_commit.
Release Transaction Safety
Publishing a plugin is treated as a multi-step transaction managed by release_transaction.py. This ensures that assets are never partially published or overwritten.
Transaction Phases
- Claim: Create a Git tag and a matching Draft release. If the tag already exists, the process fails closed.
- Upload: Upload built assets (
.tar.gzor.zip) to the specificrelease_idof the claimed draft. - Finalize: Verify that the remote asset set (names, sizes, and digests) matches the local build artifacts exactly before marking the release as public.
- Cleanup: If any step fails, the script deletes the tag and the draft release.
Sources: scripts/release_transaction.py:47-190, scripts/ensure_release_absent.py:20-56
Asset Verification Logic
During finalization, the system performs a cryptographic comparison between local artifacts and the assets already uploaded to GitHub.
Workflow Security Gating
The project employs meta-tests in test_workflow_safety.py to ensure that GitHub Actions workflows do not introduce security regressions.
Enforced Workflow Rules
- Action Pinning: Every GitHub Action must be pinned to a 40-character commit SHA, not a mutable tag.
- Permission Scoping: Only the specific
releasejob is permittedcontents: writeaccess. All other jobs and workflows are restricted tocontents: read. - Manual Dispatch: The publication workflow is restricted to
workflow_dispatchand cannot be triggered bypushorpull_requestevents. - Shell Safety: Workflow expressions
${{ ... }}are forbidden withinrun:blocks to prevent command injection; they must be passed via environment variables.
Sources: scripts/test_workflow_safety.py:53-110, REVIEW.md:33-35
Asset Packaging and Spec Generation
To ensure reproducible builds, the packaging process normalizes archive metadata.
Deterministic Packaging
The package_plugin.py script uses a fixed timestamp (1980-01-01) and standardizes Unix permissions (0o755) for all archives. This ensures that rebuilding the same binary results in an identical SHA256 hash.
Sources: scripts/package_plugin.py:27-30, README.md:26-29
Spec Integrity
The gen_spec.py script generates the final metadata used by numan-registry. It intentionally omits SHA256 hashes to force the registry-side intake script to independently download and re-hash the assets, providing an additional layer of verification.
Sources: scripts/gen_spec.py:9-18, REVIEW.md:30-31
Summary of Safety Measures
The safety checks in numan-plugins create a robust barrier against compromised binaries and configuration drift. By combining manifest validation, upstream tag verification, transactional release management, and strict workflow security, the project ensures that every plugin binary delivered to users is a faithful, immutable representation of its source code.
Sources: README.md:21-29, REVIEW.md:43-52