Add Workflow to your project
This page adds the Stella Ops Workflow packages to a .NET solution and keeps them reproducible. You configure the feed, choose the packages for each project, pin one version for the whole line, restore with a lock file, check the signature of a package, and, on a machine without a network, install from the offline archive of a release. Getting started then builds a first workflow host on top of it.
Prerequisites
- The .NET 10 SDK. The packages target
net10.0. - Access to the Stella Ops feed,
https://nuget.stella-ops.org/v3/index.json. Anyone can download from it without an account. - Access to nuget.org, or to a mirror of it that your organisation approves. The Workflow packages depend on third-party packages (for example
Npgsql,MongoDB.DriverandMicrosoft.Extensions.Http.Resilience) that the Stella Ops feed does not serve.
1. Configure the feed
Put a nuget.config beside your solution. Package source mapping takes every StellaOps.* package from the Stella Ops feed and every other package from nuget.org:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<!-- The Workflow packages come from the Stella Ops feed, every other package from nuget.org.
Package source mapping keeps StellaOps.* off nuget.org. -->
<packageSources>
<clear />
<add key="stella-ops" 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="stella-ops">
<package pattern="StellaOps.*" />
</packageSource>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>
- The longest matching pattern wins: every
StellaOps.*id comes fromstella-ops, every other id fromnuget.org. A package with the same id on another feed cannot replace a Workflow package. <clear />keeps the sources of your user-wide and machine-wide NuGet configuration out of the restore.- To use an internal mirror instead of nuget.org, change the
valueof thenuget.orgsource and keep the mapping.
2. Choose the packages
Keep the workflow definitions in a library of their own, and the engine in the host that runs them.
| Project | Packages |
|---|---|
| A library of workflow definitions | StellaOps.Workflow.Abstractions: the builder, the contracts and the analyzer |
| An ASP.NET Core host on PostgreSQL | StellaOps.Workflow (the engine and the PostgreSQL store), StellaOps.Workflow.AspNetCore (the HTTP API) |
| An ASP.NET Core host on MongoDB | StellaOps.Workflow.Engine, StellaOps.Workflow.DataStore.MongoDB, StellaOps.Workflow.AspNetCore |
| A host whose workflows call services | Add one transport per address kind: StellaOps.Workflow.Transport.Http (endpoint and http), StellaOps.Workflow.Transport.GraphQL, StellaOps.Workflow.Transport.RabbitMq |
| Several nodes with Redis wake-ups | Add StellaOps.Workflow.Signaling.Redis |
| Diagrams | Add StellaOps.Workflow.Renderer.ElkSharp (layout) and StellaOps.Workflow.Renderer.Svg (SVG) |
| A pipeline that publishes definitions to a host | StellaOps.Workflow.Publisher |
The other members of the line (StellaOps.Workflow.Contracts, StellaOps.Workflow.Contracts.Durability, StellaOps.Workflow.Analyzer, StellaOps.Workflow.Persistence, StellaOps.Workflow.DataStore.PostgreSQL, StellaOps.Infrastructure.Postgres, StellaOps.ElkSharp) and the shared foundation libraries come as dependencies. Packages lists every package with its role and licence, and the .NET API reference has a page per package with its public types and members.
3. Pin one version for the line
Every Workflow package of a release has the same version and was built from the same commit, and each member names that version of the other members as its minimum. Give every Workflow package the same version; a mix of releases restores a combination that no release built and tested.
Versions have the form x.y.z-yyyyMMddTHHmmssZ: the release number, then the UTC time of the release. NuGet reads the time as a prerelease label, so name the version exactly. Browse the released versions at https://nuget.stella-ops.org.
Central package management keeps the line on one version. In Directory.Packages.props at the root of the solution:
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<!-- One version for every Workflow package: the version of a release on the feed. -->
<StellaOpsWorkflowVersion>1.0.0-20261110T090000Z</StellaOpsWorkflowVersion>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="StellaOps.Workflow" Version="$(StellaOpsWorkflowVersion)" />
<PackageVersion Include="StellaOps.Workflow.Abstractions" Version="$(StellaOpsWorkflowVersion)" />
<PackageVersion Include="StellaOps.Workflow.AspNetCore" Version="$(StellaOpsWorkflowVersion)" />
<PackageVersion Include="StellaOps.Workflow.Transport.Http" Version="$(StellaOpsWorkflowVersion)" />
<PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
</ItemGroup>
</Project>
The version above shows the form only; put the version of a release the feed lists. The project files then name the packages without a version. The workflow library:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="StellaOps.Workflow.Abstractions" />
</ItemGroup>
</Project>
The host:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="StellaOps.Workflow" />
<PackageReference Include="StellaOps.Workflow.AspNetCore" />
<PackageReference Include="StellaOps.Workflow.Transport.Http" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Contoso.Approvals.Workflows\Contoso.Approvals.Workflows.csproj" />
</ItemGroup>
</Project>
To upgrade the line, change StellaOpsWorkflowVersion and nothing else (Upgrading).
Without central package management, name the version in every command and keep them equal:
dotnet add Contoso.Approvals.Host package StellaOps.Workflow --version 1.0.0-20261110T090000Z
dotnet add Contoso.Approvals.Host package StellaOps.Workflow.AspNetCore --version 1.0.0-20261110T090000Z
4. Restore with a lock file
A lock file records the exact version and content hash of every package the restore resolved, so every build restores the same packages. In Directory.Build.props at the root of the solution:
<Project>
<PropertyGroup>
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>
</Project>
Run
dotnet restoreand commit thepackages.lock.jsonfile it writes beside each project.In CI, restore with
dotnet restore --locked-mode.Expected result: the restore fails when the lock file no longer matches the projects’ dependencies or a package’s content hash, instead of changing the build.
After you change
StellaOpsWorkflowVersion, rundotnet restore --force-evaluate, review the changes of the lock files, and commit them.
5. Check the signature of a Workflow package
Every package on the feed is signed. NuGet does not check these signatures when it restores, so check them before a first use, in a release pipeline, or when you copy packages into an internal mirror. The commands need openssl, sha256sum and base64 in a POSIX shell (on Windows, Git Bash or WSL). The example checks StellaOps.Workflow.Engine at the version form above.
Download
cosign.pub,nuget-signing-keys.txtandnuget-signing-keys.txt.sigfromhttps://stella-ops.org/keys/into an empty folder, and check the release key id:sha256sum cosign.pubExpected result:
91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs.Check the keyring with the release key:
base64 -d nuget-signing-keys.txt.sig > keyring.sig.der openssl dgst -sha256 -verify cosign.pub -signature keyring.sig.der nuget-signing-keys.txtExpected result:
Verified OK.In the keyring, find the line that is not
revokedand whose validity window holds the timestamp of the package version (20261110T090000Z). Download the key file it names, for examplenuget-signing.pub, fromhttps://stella-ops.org/keys/, and check that its SHA-256 equals the first field of the line:sha256sum nuget-signing.pubDownload the package and its signature. The feed serves them under lower-case names:
https://nuget.stella-ops.org/v3/flatcontainer/stellaops.workflow.engine/1.0.0-20261110t090000z/stellaops.workflow.engine.1.0.0-20261110t090000z.nupkg, and the same address with.sigappended.Check the package with the package key:
base64 -d stellaops.workflow.engine.1.0.0-20261110t090000z.nupkg.sig > package.sig.der openssl dgst -sha256 -verify nuget-signing.pub -signature package.sig.der \ stellaops.workflow.engine.1.0.0-20261110t090000z.nupkgExpected 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 release, repeat steps 4 and 5 for every Workflow package at that version. The key chain, its statuses and its rotation are described in Installing Stella Ops packages.
6. Install without a network
A Workflow release can also be published as one archive, stellaops-nuget-workflow-<version>.tar.gz, with its SHA-256 in stellaops-nuget-workflow-<version>.tar.gz.sha256 beside it. Its packages/ folder is a local NuGet feed with every Workflow package of the release, the Stella Ops packages they depend on, and the signature of each package; its keys/ folder holds the keys of step 5. It holds no third-party package.
Check the archive against its published digest, extract it, and check its files:
sha256sum --check stellaops-nuget-workflow-1.0.0-20261110T090000Z.tar.gz.sha256 tar -xzf stellaops-nuget-workflow-1.0.0-20261110T090000Z.tar.gz cd stellaops-nuget-workflow-1.0.0-20261110T090000Z sha256sum --check SHA256SUMSExpected result:
OKfor every file. These digests come from the same place as the archive: they prove that the files are complete, not who published them. The next step proves the origin.Check the keys and every package in
packages/as in steps 1 to 5 of section 5 above, with the files ofkeys/andpackages/instead of downloads. The release key id must be91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b: never accept an id the archive supplies. Every package must answerVerified OK.Check that the release record names this line and version, and that the SHA-512 of each Workflow package equals its
member:line:cat release-record.txt sha512sum packages/*.nupkgExpected result:
line: workflow,version: 1.0.0-20261110T090000Z, and onemember:line per Workflow package whose SHA-512 matches.Map
StellaOps.*to the extractedpackages/folder innuget.config, and keep a source for every other id:<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <clear /> <add key="stella-ops-offline" value="stellaops-nuget-workflow-1.0.0-20261110T090000Z/packages" /> <add key="mirror" value="https://nuget.contoso.example/v3/index.json" /> </packageSources> <packageSourceMapping> <packageSource key="stella-ops-offline"> <package pattern="StellaOps.*" /> </packageSource> <packageSource key="mirror"> <package pattern="*" /> </packageSource> </packageSourceMapping> </configuration>A relative path is read from the folder of the
nuget.config. Themirrorsource stands for the internal mirror or local folder that holds the third-party packages.
Pitfalls
- Naming only the Stella Ops feed with
--source. The restore then fails on the first third-party dependency that is not in the local package cache. Keep both sources and the mapping. - Floating versions.
--prereleaseadds the newest release of that moment, andVersion="1.0.0-*"resolves to the newest release at every restore that has no lock file. Pin the exact version. - Two versions of the line. A project that references
StellaOps.Workflowat one version andStellaOps.Workflow.Transport.Httpat another restores a combination no release built. Keep one property for the line. - Warnings as errors.
StellaOps.Workflow.Abstractionsbrings the workflow analyzer into every project that references it. Its warning WF021 (a workflow the build-time bundle leaves to the runtime compiler) fails a build withTreatWarningsAsErrors. Keep it a warning with<WarningsNotAsErrors>$(WarningsNotAsErrors);WF021</WarningsNotAsErrors>, or change the construct (Analyzer).
Troubleshooting
| Symptom | Cause | Action |
|---|---|---|
Unable to find package StellaOps.Workflow | The nuget.config does not map StellaOps.* to the feed, or the version is not on the feed | Check the mapping; browse https://nuget.stella-ops.org for the versions |
| A third-party package is not found | The restore reads only the Stella Ops feed | Keep nuget.org or your mirror in packageSources and in the mapping |
NU1603, or a Workflow package at a version you did not ask for | A float or a minimum version resolved to another release | Pin every Workflow package to one version |
NU1004 in CI | The lock file differs from the resolved packages | Restore locally, review the lock file change, commit it |
| The package manager lists no versions | Prerelease versions are hidden | Name the version, or tick Include prerelease |
