Automate semantic versioning + NuGet package publishing in CI

[ottobolyos]

@PatrickRitchie, I wanted to put an idea on your radar now that the repository has a working CI surface again.

Two pieces of the release process currently look manual, and both are good candidates for automation:

• Versioning. The package version is hand-set in the root Directory.Build.props (<VersionPrefix>6.9.0</VersionPrefix>, empty <VersionSuffix>). Every release means editing that line and remembering to keep it in step with what actually shipped.
• Publishing. There's no release/publish workflow in .github/workflows/ — the only workflow is build-test-coverage (dotnet.yml), which explicitly carries no package-write privileges. So the per-library NuGet packages are presumably packed and pushed to nuget.org by hand.

I don't know what your current release ritual looks like (you may well have a local script that does this cleanly), so treat the below as a question as much as a proposal: would CI-driven versioning + publishing be useful, or do you prefer keeping releases a manual, deliberate act? If the latter, no problem — this is purely an offer.

What automation could look like

Versioning — replace the hand-bumped VersionPrefix with a deterministic, git-derived version so the version is always a function of the commit rather than a line someone remembered to edit. Two well-trodden options:

• MinVer — version comes from the nearest git tag (e.g. tag v7.0.0 → packages version 7.0.0); commits past the tag get a height-based pre-release suffix automatically. Zero config beyond a package reference; no build-time network.
• Nerdbank.GitVersioning — a version.json at the root drives versions and gives you a stable, reproducible build version + git-height. Slightly more ceremony, slightly more control.

Either removes the manual Directory.Build.props edit and makes "what version is this?" answerable from git describe.

Publishing — a release.yml workflow triggered on a published GitHub Release (or a v* tag push) that:

1. builds + tests the solution (or reuses the existing build-test-coverage job),
2. dotnet packs every shipped library in Release,
3. dotnet nuget pushes the resulting .nupkg/.snupkg to nuget.org.

For the push credential there are two routes — a classic NUGET_API_KEY repository secret, or NuGet's trusted publishing (OIDC), which avoids a long-lived key entirely by exchanging the workflow's OIDC token for a short-lived nuget.org credential. I'd lean towards trusted publishing if you're open to it, since there's no secret to rotate or leak.

Pros

• Releases become a single deliberate action — cut a tag / publish a Release, and the right version ships automatically. No "I forgot to bump the version" or "the tag and the package version disagree" classes of mistake.
• Reproducible versions — the version is derived from the commit, so a given commit always produces the same version, and the shipped version is traceable back to an exact tag.
• Lower bus-factor — the release process lives in the repo as a reviewable workflow rather than in a local script on one machine.

Cons / things to weigh

• Loss of a manual gate. Automated publish means a tag (or Release) is the trigger; if you value a hands-on "push to nuget.org myself" final step, an automated workflow removes it. Gating the push job behind a manual environment approval keeps a human in the loop while still automating everything up to the push.
• Credential setup. Trusted publishing needs a one-time policy configured on nuget.org for the org/repo; the API-key route needs a secret added. Both are quick but are your-side actions.
• Multi-target surface. The libraries multi-target (net46.1 … net9.0); a release build that produces all target frameworks is heavier than the net8.0-only Debug builds CI runs today. Worth confirming the Release multi-target build is green on a clean runner before wiring the push.

Offer

If any of this is appealing, I'm happy to prototype it — e.g. a draft PR adding MinVer + a release.yml that packs and pushes on tag, with the push gated behind a manual environment approval so you stay in control of the actual publish. If you'd rather keep releases manual, that's a perfectly good answer too; I just wanted to flag the option while CI is fresh on everyone's mind.

[PatrickRitchie]

There is an MTConnect.NET-Builder project under the build directory that is a CLI tool I have been using to create an installer for Windows, Docker Image, and Nuget packages. The only thing missing from the repo is the GitHub Token (for publishing a Release) and the Nuget API Token. There should be some kind of token needed for Docker but I usually login through the Docker CLI. These are set in a config file in that project.

The version is read from the Directory.Build.props as you mentioned, but that could be improved as you suggested to enable better functionality with git.

The installer uses InnoSetup to create an installer for Windows. If you can figure out how to run that in a GitHub Action/Workflow that would be awesome! That was my plan but I never got around to it.

I typically run the builder CLI using the following commands:

• libraries nuget build
• libraries nuget publish
• agent docker build
• agent docker publish
• agent installer build
• github release publish

I ended up creating a CLI in c# because I work better in that language. I was using Gulp but I was limited in what I could do in that. Feel free to edit/expand the existing CLI tool to run in an automated workflow or if you can come up with something better that would be great too!

[ottobolyos]

@PatrickRitchie, thanks for pointing me at the Builder—that’s the missing piece I needed before sketching the CI flow. The proposal below.

Porting the Builder logic to tools/—TypeScript everywhere

The Builder ships a dotnet CLI binary; the capability set (dotnet pack, dotnet nuget push, Docker build / push, iscc + the installer.iss, GitHub Release create via Octokit) is exactly right. I’d port each capability out of the dotnet binary and into tools/ as TypeScript, run via tsx. Any genuine one‑liner shell‑out (dotnet pack, docker buildx, iscc, gh release create) goes inline in the workflow step that needs it, not as a committed .sh / .ps1 file under tools/. Motivation: a dotnet CLI tool needs dotnet restore + dotnet build on every CI invocation (roughly a minute on a warm runner, more on cold cache) and that happens twice—once in the PR pipeline, then again on the merge commit when the release runs. TypeScript under tsx invokes instantly with no build step.

The hard rule I’d want to bake in: the merge commit and the released bits share a parent SHA. The PR CI run on that SHA already proved build + tests green; the release workflow downloads the artefacts the PR run produced (via actions/upload-artifact cross‑run lookup) and goes straight to pack / sign / publish. The only new commit the release workflow produces is the version‑bump + tag commit on top of the verified SHA.

tools/ restructure—subfolders, never bare files

tools/
├── release/   ← pack / push / sign / docker / installer / gh release
├── dev/       ← local dev-loop helpers
├── docs/      ← reference generation
└── ci/        ← shared helpers the workflows call

The docs site grows a dedicated page describing every script in every subfolder—purpose, inputs, outputs, when CI calls it, how to invoke locally. Same for every workflow under .github/workflows/ and every dev procedure (cut a branch, run tests, run the docs site, raise a PR, request a review). The principle: nothing committed to the repo is undocumented; the docs site is the index.

Versioning—keep the current uniform scheme, drive bumps from commit messages

Uniform versioning stays: every shipped package keeps inheriting <VersionPrefix> from Directory.Build.props; every release republishes every package at the same version. The hand‑edit to Directory.Build.props becomes the only thing that changes—replaced with a commit‑message‑driven semver bump on every merge to master, following the standard conventional‑commits map:

Bump	Commit types
major	BREAKING CHANGE: footer OR ! after type (overrides every row below)
minor	feat, enh
patch	fix, perf, refactor, revert
no bump	chore, docs, style, test, ci, build

Highest bump in the merge range wins. Every merge that carries at least one release‑worthy commit produces a *-dev.N pre‑release (-dev.N counter starts at 0 after any higher‑component bump). A stable cut happens only when a specially‑titled PR—chore(release): publish new stable—lands on master; the workflow strips the dev suffix off the latest dev tag, tags + publishes the stable.

So the tag‑to‑publish flow has two modes:

• Auto dev pre‑release on every merge. nuget.org receives a new 6.10.0-dev.0, 6.10.0-dev.1, etc. Consumers on stable see nothing change; consumers who opt into pre‑releases get every merge.
• Manual stable via the chore(release): publish new stable PR title. nuget.org receives the stable v6.10.0; :latest Docker tag promotes.

A commitlint.config.mjs at the repo root pins the type / scope set; a pre-merge CI gate runs commitlint --from <prior-release-tag> --to HEAD on every PR. A commit that violates the gate blocks the PR until rewritten. Plugin set: @commitlint/cli, @commitlint/config-conventional, commitlint-plugin-selective-scope.

The release commit produced by CI would be GPG‑signed by a bot identity whose public key is registered on your maintainer profile. GPG_PRIVATE_KEY + GPG_PASSPHRASE as repo secrets; standard crazy-max/ghaction-import-gpg@v6 flow.

One small convention detail: I’d switch to bare semver (6.10.0, 6.10.0-dev.3) for new tags going forward to match the NuGet / npm / Docker tag conventions for package releases. The existing v6.x.x tags stay as immutable history; only new tags drop the v. (Prose stays v6.10.0 / version 6.10.0—the v disambiguates in text; the tag itself is bare.)

Lefthook—git hook tool for the commitlint gate (and more)

There’s no git‑hook tooling installed in the repo today (no husky, no lefthook, no pre‑commit). For the commitlint gate to fire client‑side (catching a bad commit message before push, where the cost to fix it is zero) we’d want one—I’d suggest lefthook. Go‑native, fast, no node runtime needed to execute, single YAML config at the repo root:

# lefthook.yml
commit-msg:
  commands:
    commitlint:
      run: npx commitlint --edit {1}

pre-commit:
  commands:
    format-staged:
      glob: "*.{cs,csproj}"
      run: dotnet format whitespace --include {staged_files}
      stage_fixed: true

Install: npm install --save-dev lefthook, then npx lefthook install. Each contributor runs npx lefthook install once after cloning; thereafter every commit is gated. The CI pre-merge gate stays in place as the authoritative check; lefthook just catches problems earlier.

Inno Setup in CI—answering the open question

Inno Setup 6.7.1 is preinstalled on the windows-latest runner image (both windows-2022 and windows-2025), with iscc.exe already on PATH at C:\Program Files (x86)\Inno Setup 6\ISCC.exe. The installer step is literally run: iscc installer.iss on a runs-on: windows-latest job—no install step, no marketplace action required.

Code‑signing the installer is the wrinkle. Three viable flows in 2026:

1. signtool sign /f cert.pfx with a base64‑encoded PFX in a CI secret. Easiest, but CA/B Forum rules since 2023 forbid OV/EV private keys outside an HSM, so this only works with legacy certs or self‑signed.
2. Azure Artifact Signing (renamed from Trusted Signing in January 2026)—Microsoft’s recommended path. ~US$10/month, Microsoft‑verified identity for the org. Azure/artifact-signing-action@v2 with OIDC federated credentials—no long‑lived secret.
3. SignPath Foundation—free for qualifying open‑source projects, referenced by Microsoft Learn as the canonical OSS path. OV‑level certs only, but the EV ‘instant SmartScreen bypass’ was removed in 2024, so EV and OV now have identical first‑launch reputation behaviour.

For an open‑source project I’d lean SignPath Foundation: zero cost, the cert lives in their HSM, GitHub Action wires it in with three secrets. Order matters—sign every binary under publish/ first, then iscc builds the installer, then sign the installer itself. Both layers Authenticode‑signed.

If signing is too much to take on right now, the workflow can ship an unsigned installer with the rest, and we add signing as a follow‑up PR.

Optional add‑ons for the release pipeline

Each gated on your call; each adds CI runtime. Happy to include any combination in the first cut or defer to follow‑ups.

• Multi‑arch Docker images (linux/amd64 + linux/arm64) via parallel native runners on ubuntu-latest (amd64) + ubuntu-24.04-arm (arm64), combined with a docker manifest step at the end. Both legs build natively; total runtime is roughly max(amd64, arm64) + a few seconds for the manifest combine—near‑zero overhead vs single‑arch today. Native arm64 runners are free for public repos.
• SBOM generation—CycloneDX or SPDX SBOM produced per release and attached to the GitHub Release. dotnet sbom-tool for the .NET side, syft or docker scout sbom for the Docker image. Useful for downstream consumers doing supply‑chain attestation. Adds ~30 seconds.
• Docker image signing—Cosign keyless signing via OIDC, no key to rotate. Pushes the signature as an OCI artefact alongside the image so consumers can verify cosign verify trakhound/mtconnect-agent:6.10.0. Adds a few seconds.
• Vulnerability scanning—aquasecurity/trivy-action against the .nupkg set and the Docker image, results uploaded as SARIF to the GitHub Security tab. Catches known‑CVE dependencies. Adds 30–60 seconds.
• Scheduled deps‑update workflow—a separate deps-update.yml running weekly (e.g. Saturday 02:00 UTC) that bumps every dependency at once in one PR: GitHub Actions plugin versions, Docker base images, npm packages under docs/, and NuGet packages across every .csproj. The whole bundle runs the standard CI matrix on that single PR; everything is verified to compile + test green against the new dep set together. If every check passes the workflow auto‑merges it; if any check fails the PR stays open for your review (auto‑merge vs always‑manual is your toggle). A subsequent scheduled run while a deps‑update PR is still open supersedes it: the new PR replaces the prior one and the prior is auto‑closed. This means the merge stream never accumulates more than one open deps PR, and the maintenance burden of ‘is this dep set still current?’ stays at zero. No dependabot.yml, no Renovate—this is a single self‑contained workflow we own and can shape to whatever security policy you want.

CI secrets you’d need to define

Secret	Purpose	Required / optional
NUGET_API_KEY	dotnet nuget push to nuget.org. Alternative: NuGet trusted publishing (OIDC)—no secret, federated identity. Worth considering for rotation hygiene.	Required for release.yml
DOCKERHUB_USERNAME + DOCKERHUB_TOKEN	docker login before docker push trakhound/.... Personal access token, not password.	Required for Docker push
GH_TOKEN	Only needed for cross‑repo writes or scopes beyond contents: write. The default ${{ secrets.GITHUB_TOKEN }} is enough for gh release create and actions/upload-artifact within this repo.	Optional
GPG_PRIVATE_KEY + GPG_PASSPHRASE	Signed release commit + signed tags. Standard crazy-max/ghaction-import-gpg@v6 flow.	Recommended
Authenticode signing secrets (whichever flow)	Per the signing section above. SignPath Foundation: SIGNPATH_API_TOKEN + a signing‑policy reference.	Optional

What I’d like to do next

If you’re happy with this shape, I’ll open a draft PR that:

1. Adds tools/release/*.ts—the porting scripts (no release.yml yet; scripts run cleanly from a developer machine first).
2. Restructures tools/ into the subfolder layout above.
3. Adds the docs‑site pages describing every workflow, every script, every dev procedure.
4. Adds commitlint.config.mjs at the repo root, lefthook.yml for the client‑side hook, and a pre-merge CI gate.
5. Adds release.yml triggered on master push, with the dev‑on‑every‑merge auto‑prerelease flow and the chore(release): publish new stable PR‑title‑driven stable cut.
6. Leaves build/MTConnect.NET.Builder/ in place for one release cycle so we can validate the new flow against the old one before deletion.
7. Defers the optional add‑ons (signing, multi‑arch, SBOM, Docker image signing, vulnerability scanning, deps‑update) to follow‑up PRs unless you’d like any of them in scope from the start.

Four questions for you before I cut the branch:

1. Signing right away, or follow‑up? Either is fine; just lets me size phase 1.
2. NuGet trusted publishing, or classic API key? Trusted publishing is the more modern option (no secret to rotate) but needs a one‑time policy configured on nuget.org for the repo.
3. Which optional add‑ons (multi‑arch Docker, SBOM, Docker image signing, vulnerability scanning, scheduled deps‑update) do you want in the first cut?
4. If deps‑update is in scope: dep freshness policy. Two sub‑questions. (a) Should the workflow install the absolute latest version of every dep, or only versions that are at least N days old (e.g. 7 days)? A short quarantine window is the standard defence against supply‑chain attacks—a compromised package released minutes ago typically gets flagged and yanked within a few days, so consuming only N‑day‑old versions cuts the realistic exposure window dramatically. (b) Auto‑merge the green deps PR, or always require your manual merge? Auto‑merge ships patches faster; manual gives you a deliberate review checkpoint. Either is fine—happy to wire both modes behind a single config knob.

Once you confirm direction, I’ll have a draft PR up shortly after. (Independent of this—I’m separately fixing the AVAILABILITY‑style observation Result issue where an empty / whitespace value reaches the wire instead of UNAVAILABLE; that’ll arrive as its own PR with a fully self‑contained description.)

[ottobolyos]

@PatrickRitchie, while you decide, could you release a dev/rc/pre-release from the master branch please? 🙏