stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
68da90a11a3f12708a9492c56f3cf439732978af
git.stella-ops.org/docs/ops/nuget-preview-bootstrap.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +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.