Installing Stella Ops packages

Stella Ops publishes its .NET components as NuGet packages: the Router (a gateway and the microservices behind it), the Workflow engine, and the shared foundation libraries they use. This guide covers what every consumer does once: configure the feed, choose and pin versions, check package signatures, and install from the offline archive on a machine without a network.

For the packages of one component and the role of each, read the component’s package page: Router packages and Workflow packages.

Before you start

If the feed lists no version of a package, that package has not been released yet.

Configure the feed

Put a nuget.config beside your solution. It takes every StellaOps.* package from the Stella Ops feed and every other package from nuget.org, with package source mapping:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="stellaops" value="https://nuget.stella-ops.org/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="stellaops">
      <package pattern="StellaOps.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

How it works:

To use an internal mirror instead of nuget.org, change the value of the nuget.org source and keep the mapping.

Pitfall. Do not name the Stella Ops feed alone with --source. A restore that reads only that feed fails when a third-party dependency is not already in the local package cache.

Add a package

Every version is a prerelease in NuGet’s terms (see Versions), so name the version or pass --prerelease:

dotnet add package StellaOps.Microservice --prerelease
dotnet add package StellaOps.Workflow --prerelease

In Visual Studio, tick Include prerelease in the package manager. dotnet package search reports that the feed has no search service. Browse the packages, their versions and their release notes at https://nuget.stella-ops.org.

The Router gateway is also published as a .NET tool, StellaOps.Router.Gateway.Host. Router gateway host shows how to install and run it.

Versions

Every version has the form x.y.z-yyyyMMddTHHmmssZ, for example 1.2.3-20261102T141530Z: the release number, then the UTC time of the release. A plain x.y.z is never published. NuGet clients cache a version permanently, so a published version never changes.

NuGet reads the time suffix as a prerelease label. Choose the form that matches your goal:

GoalUse
The newest release, oncedotnet add package <id> --prerelease
One exact release, for reproducible builds--version 1.2.3-20261102T141530Z, or Version="1.2.3-20261102T141530Z" in the PackageReference
The newest release of 1.2.3 at each restoreVersion="1.2.3-*" in the PackageReference

One version for a line

The Router packages form one line, and the Workflow packages form another. Every member of a line release has the same version and was built from the same commit. A member names that version of the other members as the minimum version of its dependency on them. Mixing versions of one line restores a combination that no release built and tested.

Keep a line on one version with central package management. In Directory.Packages.props at the root of the solution:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <StellaOpsRouterVersion>1.2.3-20261102T141530Z</StellaOpsRouterVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="StellaOps.Microservice" Version="$(StellaOpsRouterVersion)" />
    <PackageVersion Include="StellaOps.Microservice.SourceGen" Version="$(StellaOpsRouterVersion)" />
    <PackageVersion Include="StellaOps.Router.Transport.Tcp" Version="$(StellaOpsRouterVersion)" />
  </ItemGroup>
</Project>

The project files then name the packages without a version (<PackageReference Include="StellaOps.Microservice" />). To upgrade the line, change one property. The version above shows the form only; use a version the feed lists.

The shared foundation libraries (for example StellaOps.Messaging) are released one library at a time, each with its own version. A line member names the foundation version it was built with, and NuGet restores it as a dependency, so you do not reference it yourself unless your code uses it.

Reproducible restores with a lock file

A float such as 1.2.3-* resolves to the newest release at each restore. For a build that restores the same packages every time, pin exact versions and use a lock file:

  1. In each project, or once in Directory.Build.props, set the property:

    <PropertyGroup>
      <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    </PropertyGroup>
    
  2. Run dotnet restore and commit the packages.lock.json file it writes beside each project.

  3. In CI, restore with dotnet restore --locked-mode. Expected result: the restore fails when the lock file no longer matches the project’s dependencies or a package’s content hash, instead of changing the build.

Checking a package’s signature

Every package on the feed is signed. NuGet does not check these signatures when it restores, so check them yourself when it matters: before a first use, in a release pipeline, or when you copy packages into an internal mirror.

The chain of keys

Four links, each checked with openssl:

  1. The release key, https://stella-ops.org/keys/cosign.pub. Its SHA-256 is its key id, and the key id is fixed: 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. The same key signs Stella Ops images and release bundles. It never signs a package itself.
  2. The keyring, https://stella-ops.org/keys/nuget-signing-keys.txt. It verifies with the release key, using nuget-signing-keys.txt.sig beside it.
  3. The package key. The keyring line whose validity window holds the timestamp in the package version, and which is not revoked. The key file it names, such as nuget-signing.pub, sits beside the keyring, and its SHA-256 must equal the first field of the line.
  4. The package. Its .sig file, served beside the package, verifies with the package key.

Each keyring line has five fields:

<sha256 of the key file> <status> <valid-from> <valid-until> <file>

The two times have the version form yyyyMMddTHHmmssZ. A key is valid for a package when valid-from is at or before the package’s timestamp and valid-until is after it. Windows may overlap while a new key takes over. The status is one of:

StatusMeaning
activeSigns new packages.
retiredSigns nothing new. Packages it signed inside its window still verify.
revokedNothing it signed verifies, whatever the date.

A signature proves that the Stella Ops release host built and published the package from a commit on the main branch, after the release checks. It does not prove that a person reviewed the code.

Check one package

Download each file over HTTPS with any client and keep its file name. The commands need openssl, sha256sum and base64 in a POSIX shell (on Windows, Git Bash or WSL).

  1. Download the release key and the keyring into an empty folder: cosign.pub, nuget-signing-keys.txt and nuget-signing-keys.txt.sig from https://stella-ops.org/keys/.

  2. Check the release key id:

    sha256sum cosign.pub
    

    Expected result: 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs: a key with another id is not the Stella Ops release key.

  3. Check the keyring:

    base64 -d nuget-signing-keys.txt.sig > keyring.sig.der
    openssl dgst -sha256 -verify cosign.pub -signature keyring.sig.der nuget-signing-keys.txt
    

    Expected result: Verified OK.

  4. Read the timestamp from the package version (20261102T141530Z in 1.2.3-20261102T141530Z). Find the keyring line that is not revoked and whose window holds that timestamp. Download the key file it names from https://stella-ops.org/keys/, then compare its SHA-256 with the first field of the line:

    sha256sum nuget-signing.pub
    
  5. Download the package and its signature. The feed serves them under lower-case names: https://nuget.stella-ops.org/v3/flatcontainer/<id>/<version>/<id>.<version>.nupkg and the same address with .sig appended. For StellaOps.Microservice 1.2.3-20261102T141530Z, <id> is stellaops.microservice and <version> is 1.2.3-20261102t141530z.

  6. Check the package:

    base64 -d stellaops.microservice.1.2.3-20261102t141530z.nupkg.sig > package.sig.der
    openssl dgst -sha256 -verify nuget-signing.pub -signature package.sig.der \
      stellaops.microservice.1.2.3-20261102t141530z.nupkg
    

    Expected result: Verified OK. Any other output means the package is not the one the release host published: do not use it.

To check a whole line release, repeat steps 5 and 6 for every member at the same version. Every member must verify, and every member must carry the same version.

The offline archive of a line release

A line release can also be published as one archive for machines without a network: stellaops-nuget-<line>-<version>.tar.gz, with its SHA-256 in stellaops-nuget-<line>-<version>.tar.gz.sha256 beside it. The download page of the component gives the archive’s address and digest for each release.

The archive has one top directory, stellaops-nuget-<line>-<version>/:

PathContent
packages/A local NuGet feed: every member of the release, every Stella Ops package the members depend on at the exact version they name, and the .sig file of each package. No third-party package.
keys/cosign.pub, nuget-signing-keys.txt and its .sig, and every package key the packages need.
release-record.txt and release-record.txt.sha256The release record: the line, the version, the commit, the publication date and the SHA-512 of every member.
component-release.propsThe release properties for a rebuild of the release from its commit.
SHA256SUMSThe SHA-256 of every other file, with paths relative to the top directory.

The archive as a whole is not signed. Its integrity is the published SHA-256, and every package in it carries its own signature.

Check the archive

  1. Compare the archive with its published digest. In the folder that holds both files:

    sha256sum --check stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz.sha256
    

    Expected result: stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz: OK.

  2. Extract it and check every file:

    tar -xzf stellaops-nuget-router-1.2.3-20261102T141530Z.tar.gz
    cd stellaops-nuget-router-1.2.3-20261102T141530Z
    sha256sum --check SHA256SUMS
    sha256sum --check release-record.txt.sha256
    

    Expected result: OK for every file.

  3. Check the keys in keys/ and every package in packages/ as in Check one package, steps 2 to 4 and 6, with the files from the archive instead of downloads. The release key id must be the fixed id above: never accept an id the archive supplies.

  4. Check that release-record.txt names the line and version of the archive name, and that the SHA-512 of each member package equals its member: line:

    cat release-record.txt
    sha512sum packages/*.nupkg
    

Use the archive as a local feed

Map StellaOps.* to the extracted packages/ folder and keep a source for every other id:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="stellaops-offline" value="stellaops-nuget-router-1.2.3-20261102T141530Z/packages" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="stellaops-offline">
      <package pattern="StellaOps.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

A relative path is read from the folder of the nuget.config. On a machine without a network, replace the nuget.org source with a local folder or an internal mirror that holds the third-party packages, or restore them into the package cache first.

What a line release gives you

Rules for consumers

RuleWhy
Take StellaOps.* packages only from the Stella Ops feed or its offline archive, with package source mappingNuGet otherwise takes a package from whichever source answers first
Give every package of one line the same versionA member names that release’s version of the other members as its minimum; mixing releases restores a combination no release built
Pin exact versions and restore with a lock file for reproducible buildsA float such as 1.2.3-* resolves to the newest release at each restore
Expect a published version never to changeA withdrawn version is only hidden from listings; an exact reference to it still restores
Check signatures before a package enters your build or mirrorNuGet does not check these signatures on restore
Expect build-time analyzers with some packagesA package with analyzer assets runs them in every project that references it: StellaOps.Microservice.SourceGen generates the Router endpoint registration, and the Workflow abstractions package brings the workflow definition analyzer

Troubleshooting

SymptomCauseFix
Unable to find package StellaOps.<name>The nuget.config does not map StellaOps.* to the feed, or no version has been releasedCheck the mapping; browse https://nuget.stella-ops.org for the package
A third-party package is not foundThe restore reads only the Stella Ops feedKeep nuget.org or your mirror in packageSources and in the mapping
NU1603 or a version you did not ask forA float or a minimum version resolved to another releasePin the exact version of every member of the line
NU1004 in CIThe lock file differs from the resolved graphRestore locally, review the lock file change, commit it
The package manager shows no versionsPrerelease versions are hiddenPass --prerelease, or tick Include prerelease