Troubleshooting & FAQ
Relevant source files
The following files were used as context for generating this wiki page:
This page provides guidance on identifying, diagnosing, and resolving issues within the numan-plugins CI pipeline. It covers common failure modes related to manifest validation, release transactions, and build matrix constraints.
The numan-plugins repository serves as a binary-delivery feeder for the numan-registry. It automates the cross-compilation of Nushell plugins from immutable upstream commits, packages them, and publishes them as GitHub release assets. Troubleshooting often involves verifying the integrity of the trust boundary, ensuring immutable pins are correct, and managing the state of draft releases.
Sources: README.md:1-12, REVIEW.md:14-19
Build & CI Failures
The build pipeline is designed to "fail closed" to prevent inconsistent states or trust boundary breaks. Common failures occur during the validation of the manifest.json or during the cross-compilation stage.
Manifest Validation Errors
The validate_manifest.py script enforces strict schema requirements. If a build fails early, it is often due to a mismatch in the active[] entry requirements.
| Error Type | Cause | Resolution |
|---|---|---|
| Missing Fields | Required keys like source_commit or plugin_bin are absent. | Ensure all 11 required fields are present for each entry. |
| Duplicate Name | Multiple active plugins share the same name. | Rename the entry to be unique within the active list. |
| Malformed SHA | source_commit is not exactly 40 lowercase hex characters. | Use the full git commit hash from the upstream repository. |
| Target Exclusion | All default targets are excluded for a specific plugin. | Ensure at least one target remains after exclude_targets is applied. |
Sources: scripts/validate_manifest.py:16-29, scripts/validate_manifest.py:75-102
Cross-Compilation Issues
Specific plugins may fail on certain platforms due to upstream code constraints, such as GUID type mismatches or missing system headers in the cross-toolchain.
This diagram shows the branching build paths and common platform-specific failure points identified in current metadata.
Sources: manifest.json:28-31, manifest.json:89-91, scripts/test_workflow_safety.py:116-125
Release Transaction Failures
The release process uses a transactional "claim-then-finalize" pattern to ensure atomicity. If a release fails midway, it may leave a "dangling" draft or tag.
Troubleshooting Release States
The release_transaction.py script manages the state of GitHub releases. If a publication is interrupted, use the following logic to diagnose:
- Release Already Exists: The pipeline will refuse to overwrite existing assets. If a build fails with "published assets are immutable," you must increment the package version or build revision.
Sources: scripts/ensure_release_absent.py:32-34, REVIEW.md:24-24 - Tag/Commit Mismatch: If the upstream tag resolves to a different commit than the pinned
source_commit, the verification will fail.
Sources: scripts/validate_manifest.py:145-151 - Draft Cleanup: If the
finalizestep fails, thecleanupcommand is designed to delete only the draft release and the tag owned by that specific run.
Sources: scripts/release_transaction.py:175-188
Asset Verification Flow
Before a release is moved from draft: true to draft: false, the system performs an exact byte-set match verification.
Frequently Asked Questions (FAQ)
Why can't I trigger a release from my Pull Request?
Answer: By design, pushes and pull requests only validate the manifest and build logic. Releases can only be triggered via a manual workflow_dispatch with a non-empty only= package list. This preserves the trust boundary and prevents automated or unauthorized artifact publication.
Sources: REVIEW.md:11-12, scripts/test_workflow_safety.py:70-75
How do I fix a "Trust boundary break" warning (P0)?
Answer: P0 severity labels are applied if signing-key material is added to this repo or if there is an attempt to publish from a PR. Ensure no private keys (.pem) or registry secrets are ever committed. Signing must occur only in numan-registry.
Sources: REVIEW.md:14-16, REVIEW.md:20-21
What should I do if a macOS runner stalls?
Answer: Historically, macos-13 runners have stalled on certain plugin builds. The project has migrated to macos-15-intel (for x86_64) and macos-15 (for aarch64). If you encounter stalls, verify that the target_runner_map in manifest.json and the TARGETS list in the workflow are updated to the latest supported runners.
Sources: manifest.json:161-167, scripts/test_workflow_safety.py:116-125
Why is the SHA256 missing from my generated spec?
Answer: This is intentional. Hashes are not authored in this repository to prevent hand-typing errors. The numan-registry intake script (add-package.py) is responsible for downloading the assets and computing the final hashes during the registry update process.
Sources: README.md:20-22, REVIEW.md:28-28
Summary
Troubleshooting in numan-plugins focuses on maintaining the integrity of the build-and-deliver pipeline. By enforcing immutable pins, validating upstream tags against local commits, and utilizing a transactional release process, the system prevents the distribution of unauthorized or broken binary artifacts. Most issues can be resolved by correcting manifest.json entries or cleaning up stalled draft releases via the provided scripts.