stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7b5bdcf4d3bee4e6f398d0226ba8cd3c2754e07a
git.stella-ops.org/docs/modules/devops/runbooks/nuget-preview-bootstrap.md
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
2025-10-30 00:09:39 +02:00

3.0 KiB
Raw Blame History

NuGet Preview Bootstrap (Offline-Friendly)

The StellaOps build relies on .NET 10 RC2 packages (Microsoft.Extensions.*, JwtBearer 10.0 RC). NuGet.config now wires three sources:

  1. local → ./local-nuget (preferred, air-gapped mirror)
  2. dotnet-public → https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json
  3. nuget.org → fallback for everything else

Follow the steps below whenever you refresh the repo or roll a new Offline Kit drop.

1. Mirror the preview packages

./ops/devops/sync-preview-nuget.sh
  • Reads ops/devops/nuget-preview-packages.csv. Each line specifies the package, version, expected SHA-256 hash, and (optionally) the flat-container base URL (we pin to dotnet-public).
  • Downloads the .nupkg straight into ./local-nuget/ and re-verifies the checksum. Existing files are skipped when hashes already match.
  • Use NUGET_V2_BASE if you need to temporarily point at a different mirror.

💡 The script never mutates packages in place—if a checksum changes you will see a “SHA mismatch … refreshing” message.

2. Restore using the shared NuGet.config

From the repo root:

DOTNET_NOLOGO=1 dotnet restore src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Abstractions/StellaOps.Excititor.Connectors.Abstractions.csproj \
  --configfile NuGet.config

The packageSourceMapping section keeps Microsoft.Extensions.*, Microsoft.AspNetCore.*, and Microsoft.Data.Sqlite bound to local/dotnet-public, so dotnet restore never has to reach out to nuget.org when mirrors are populated.

Before committing changes (or when wiring up a new environment) run:

python3 ops/devops/validate_restore_sources.py

The validator asserts:

  • NuGet.config lists local → dotnet-public → nuget.org in that order.
  • Directory.Build.props pins RestoreSources so every project prioritises the local mirror.
  • No stray NuGet.config files shadow the repo root configuration.

CI executes the validator in both the build-test-deploy and release workflows, so regressions trip before any restore/build begins.

If you run fully air-gapped, remember to clear the cache between SDK upgrades:

dotnet nuget locals all --clear

3. Troubleshooting

Symptom Fix
dotnet restore still hits nuget.org for preview packages Re-run sync-preview-nuget.sh to ensure the .nupkg exists locally, then delete ~/.nuget/packages/microsoft.extensions.* so the resolver picks up the mirrored copy.
SHA mismatch in the manifest Update ops/devops/nuget-preview-packages.csv with the new version + checksum (from the feed) and re-run the sync script.
Azure DevOps feed throttling Set DOTNET_PUBLIC_FLAT_BASE env var and point it at your own mirrored flat-container, then add the URL to the 4th column of the manifest.

Keep this doc alongside Offline Kit instructions so air-gapped operators know exactly how to refresh the mirror and verify packages before restore.