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

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>

2. Choose the packages

Keep the workflow definitions in a library of their own, and the engine in the host that runs them.

ProjectPackages
A library of workflow definitionsStellaOps.Workflow.Abstractions: the builder, the contracts and the analyzer
An ASP.NET Core host on PostgreSQLStellaOps.Workflow (the engine and the PostgreSQL store), StellaOps.Workflow.AspNetCore (the HTTP API)
An ASP.NET Core host on MongoDBStellaOps.Workflow.Engine, StellaOps.Workflow.DataStore.MongoDB, StellaOps.Workflow.AspNetCore
A host whose workflows call servicesAdd 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-upsAdd StellaOps.Workflow.Signaling.Redis
DiagramsAdd StellaOps.Workflow.Renderer.ElkSharp (layout) and StellaOps.Workflow.Renderer.Svg (SVG)
A pipeline that publishes definitions to a hostStellaOps.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>
  1. Run dotnet restore and commit the packages.lock.json file it writes beside each project.

  2. 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.

  3. After you change StellaOpsWorkflowVersion, run dotnet 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.

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

    sha256sum cosign.pub
    

    Expected result: 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs.

  2. 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.txt
    

    Expected result: Verified OK.

  3. In the keyring, find the line that is not revoked and whose validity window holds the timestamp of the package version (20261110T090000Z). Download the key file it names, for example nuget-signing.pub, from https://stella-ops.org/keys/, and check that its SHA-256 equals the first field of the line:

    sha256sum nuget-signing.pub
    
  4. Download 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 .sig appended.

  5. 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.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 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.

  1. 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 SHA256SUMS
    

    Expected result: OK for 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.

  2. Check the keys and every package in packages/ as in steps 1 to 5 of section 5 above, with the files of keys/ and packages/ instead of downloads. The release key id must be 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b: never accept an id the archive supplies. Every package must answer Verified OK.

  3. 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/*.nupkg
    

    Expected result: line: workflow, version: 1.0.0-20261110T090000Z, and one member: line per Workflow package whose SHA-512 matches.

  4. Map StellaOps.* to the extracted packages/ folder in nuget.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. The mirror source stands for the internal mirror or local folder that holds the third-party packages.

Pitfalls

Troubleshooting

SymptomCauseAction
Unable to find package StellaOps.WorkflowThe nuget.config does not map StellaOps.* to the feed, or the version is not on the feedCheck the mapping; browse https://nuget.stella-ops.org for the versions
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 Workflow package at a version you did not ask forA float or a minimum version resolved to another releasePin every Workflow package to one version
NU1004 in CIThe lock file differs from the resolved packagesRestore locally, review the lock file change, commit it
The package manager lists no versionsPrerelease versions are hiddenName the version, or tick Include prerelease