stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Refactor NuGet package handling across multiple CI runners and documentation. Update paths to use .nuget/packages instead of local-nugets. Enhance README files for clarity on usage and environment setup. Add script to automate the addition of test projects to the solution.

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-26 21:44:32 +02:00
parent 32f9581aa7
commit 335ff7da16
19 changed files with 93 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/ops/binary-prereqs.md
View File

@@ -1,27 +1,26 @@
# Binary Prerequisites & Offline Layout
## Layout (authoritative)
- `local-nugets/` — single source for NuGet: holds curated `.nupkg` and the restored packages cache in `local-nugets/packages/`; see `local-nugets/manifest.json` for hashes of the `.nupkg` inputs.
- `vendor/` — pinned binaries/CLIs tracked via `vendor/manifest.json`.
- `offline/feeds/` — air-gap bundles (tarballs, OCI layers, SBOM packs) registered in `offline/feeds/manifest.json`.
- Module-owned binaries (currently `plugins/`, `tools/`, `deploy/`, `ops/`) are tracked for integrity in `vendor/manifest.json` until relocated.
- `.nuget/packages/` — NuGet package cache (configured via `nuget.config` `globalPackagesFolder`).
- `devops/manifests/` — binary integrity manifests (e.g., `binary-plugins.manifest.json`).
- `devops/offline/feeds/` — air-gap bundles (tarballs, OCI layers, SBOM packs) registered in `manifest.json`.
- Module-owned binaries (currently `plugins/`, `tools/`, `deploy/`, `ops/`) are tracked for integrity in `devops/manifests/` until relocated.
## Adding or updating NuGet packages
1) Place `.nupkg` into `local-nugets/` and update `local-nugets/manifest.json` (use the manifest script in `scripts/` if available or recompute hashes manually).
2) Run `dotnet restore --source local-nugets` (or set `OFFLINE=1`) to populate `.nuget/packages/`.
3) Never add new feeds to `NuGet.config` without review; the default feed order is `local-nugets` first, then `nuget.org` for online builds.
1) Run `dotnet restore` which populates `.nuget/packages/` per the sources in `nuget.config`.
2) Never add new feeds to `nuget.config` without review; the configured sources are `nuget.org` and `stellaops` (internal feed).
3) For offline builds, pre-populate `.nuget/packages/` from a network-connected machine, then copy to the air-gapped environment.
## Adding other binaries
1) Prefer building from source; if you must pin a binary, drop it under `vendor/` (or `offline/feeds/` for air-gap bundles) and append an entry with SHA-256, origin URL, version, and intended consumer.
2) For module-owned binaries (e.g., plugins), record the artefact in `vendor/manifest.json` until it can be rebuilt deterministically as part of CI.
1) Prefer building from source; if you must pin a binary, drop it under `devops/offline/` and append an entry with SHA-256, origin URL, version, and intended consumer.
2) For module-owned binaries (e.g., plugins), record the artefact in `devops/manifests/binary-plugins.manifest.json` until it can be rebuilt deterministically as part of CI.
## Automation & Integrity
- Run `scripts/update-binary-manifests.py` to refresh `local-nugets/manifest.json`, `vendor/manifest.json`, and `offline/feeds/manifest.json` after adding binaries.
- Run `scripts/update-binary-manifests.py` to refresh manifests after adding binaries.
- Run `scripts/verify-binaries.sh` locally; CI executes it on every PR/branch to block binaries outside approved roots.
- CI also re-runs the manifest generator and fails if the manifests would change—commit regenerated manifests as part of the change.
- Restore uses the single location: `dotnet restore --source local-nugets` with `globalPackagesFolder=local-nugets/packages` (configured in `NuGet.config`). Clean by removing `local-nugets/packages/` if needed.
- NuGet restore uses `.nuget/packages/` as configured in `nuget.config`. Clean by removing `.nuget/packages/` if needed.
- For offline enforcement, set `OFFLINE=1` (CI should fail if it reaches `nuget.org` without `ALLOW_REMOTE=1`).
## Housekeeping
- Do not resurrect `local-nuget/`; the single source of truth is `local-nugets/`.
- Refresh manifests when binaries change and record the update in the current sprint’s Execution Log.
- Refresh manifests when binaries change and record the update in the current sprint's Execution Log.