CI & automation
Treat supply-chain security as a requirement. Agents now write and run much of the code in a pipeline, so nobody reviews each step by hand.
Opinions
- Pin GitHub Actions to commit SHAs, not mutable tags. A tag can move without warning, and a SHA can't. Enforce pinning in every repository, and script it when you have many. (Meziantou: SHA pinning)
- Never interpolate user input into a workflow script. Pass it in an environment variable, and parse it in the script. Meziantou calls interpolating an input into a
runstep "A common but unsafe pattern". (Meziantou: Safely passing extra arguments) - Pin the SDK and every package in CI.
global.jsonsets the SDK, and lock files or Central Package Management set the packages. A CI run must never pick up a version the repository didn't choose. (Microsoft Learn: global.json overview, Meziantou: Faster and Safer NuGet restore using Source Mapping and Lock files) -
If you restore from more than one feed, use package source mapping. Without it, "If you have a package published on an internal feed... with the same name as a public package, the public package can be used instead". (Meziantou: NuGet Packages: security risks and best practices)
- Map every package to a source in one
nuget.configat the repository root. - Start its sources with
<clear/>, so no inherited source survives. - Leave no package pattern unmapped.
Mapping "applies only when NuGet downloads packages during restore, install, and update". Commands that query source metadata, such as
dotnet package add, still "send package IDs to all configured sources". (Microsoft Learn: Package Source Mapping) A repository that restores only from nuget.org gains little: with one source, a same-named package has no second feed to come from. - Map every package to a source in one
-
Treat warnings as errors in every build, with no CI condition. Set
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>in the rootDirectory.Build.props, as templates/Directory.Build.props does, so a compiler, analyzer, or NuGet warning fails on the machine that introduces it. MSBuild's own warnings, such as MSB3277, need the-warnaserrorswitch, which Pipeline shape adds in CI. Stannard enables it "because this prevents all sorts of rot from setting into the code base (i.e. NuGet package vulnerability warnings and deprecations have to be addressed immediately)". His project-structure skill and Abuhakmeh's typicalDirectory.Build.propsboth set it with noCondition. (Stannard: Software 2.0: Planning and Verifying a Greenfield Project, Stannard: project-structure, Abuhakmeh: Directory.Build.props: Share Settings Across .NET Projects) - Fix a warning instead of suppressing it, and give each suppression you keep a comment that says why. That covers
#pragma warning disable,[SuppressMessage], and a<NoWarn>entry. Revert a suppression that has none. Stannard's Slopwatch skill lists#pragma warning disableand a project-level<NoWarn>among the shortcuts an agent takes to get a passing build, and says "Never accept these patterns". It allows an exception only with a reason: "Exceptions require justification", and "Document why in a code comment". Slopwatch is his own tool.[SuppressMessage]has aJustificationproperty for the reason, and Seemann fills it in when he keeps CA2234 off one test helper. (Stannard: dotnet-slopwatch, Seemann: Warnings-as-errors friction, Microsoft Learn: Suppress code analysis warnings) -
Treat vulnerability warnings as build errors everywhere. NuGet Audit runs during restore, and "
NuGetAuditModedefaults toallwhen a project targetsnet10.0or higher", so it checks the whole graph. (Microsoft Learn: Auditing package dependencies for security vulnerabilities)TreatWarningsAsErrors, which templates/Directory.Build.props sets, turns NU1901 to NU1904 into errors. Restore then fails on the day an advisory lands, even if nobody changed the graph. That's intended: triaging the advisory is the first step in servicing the branch.- To suppress one advisory, add
NuGetAuditSuppresswith its URL, and a comment that gives the reason. (Microsoft Learn: Excluding advisories) - Never use the documented shortcut,
<WarningsNotAsErrors>NU1901;NU1902;NU1903;NU1904</WarningsNotAsErrors>. It turns the vulnerability errors back into warnings, which are the warnings that cost most to ignore. (Microsoft Learn: NuGet Warnings NU1901, NU1902, NU1903, NU1904) - Never turn the audit off in the pipeline alone, which the documentation also offers.
.NET 10 prunes platform-provided packages from the graph before the audit, so the report is shorter. In the NuGet team's telemetry, "projects with these defaults have 70% fewer transitive vulnerability reports compared to projects using the previous defaults". (Kolev: NuGet Package Pruning: Cleaner Dependencies and Actionable Vulnerability Reports)
- To suppress one advisory, add
-
Restrict what a package can run, not only which version restores. A
PackageReferencecan bring MSBuild props and targets, analyzers, and source generators. All of them run during restore, design-time build, and compile. A version pin decides which code you get, not whether it runs. List only the asset types a package needs:- Use
IncludeAssets="compile;runtime"for a library you only call. - Use
PrivateAssets="all"on build-only tooling, so it never flows to your consumers. - Under Central Package Management, set both on the
PackageReference, never thePackageVersion. APackageVersionholds a package ID and version. For tooling that every project uses, add aGlobalPackageReferencetoDirectory.Packages.propsinstead, which getsPrivateAssets="All"implicitly. NuGet 7.9 fixed a bug in whichdotnet add packagewrotePrivateAssetsto thePackageVersionitem. (Microsoft Learn: Central Package Management, Microsoft Learn: NuGet 7.9 Release Notes)
A package that's mostly build logic needs more asset types than these, so rebuild and re-test after you tighten a reference. (Meziantou: Limit what NuGet packages can do in your project)
- Use
Pipeline shape
Run four stages in order: restore, build, test, and publish. Each stage reuses the output of the one before it. Pass --no-restore to build, and --no-build to test and publish, so no stage rebuilds with different flags.
Pass the same --configuration to every stage. dotnet publish defaults to Release for current target frameworks, but for dotnet build and dotnet test, "The default for most projects is Debug". A --no-build stage with a different configuration looks for output that doesn't exist. (Microsoft Learn: dotnet publish, Microsoft Learn: dotnet build, Microsoft Learn: dotnet test with Microsoft.Testing.Platform)
- Restore. If the repository commits
packages.lock.json(RestorePackagesWithLockFile=true), pass--locked-mode, so a stale lock file fails the build. Without a lock file, the flag fails every restore withNU1004. The templates pin packages with Central Package Management in templates/Directory.Packages.props, and templates/Directory.Build.props turns lock files off, so the example restores without it. - Build. Build once, in
Release, with-warnaserror. Keep the switch even though the template setsTreatWarningsAsErrors. The property covers compiler and analyzer diagnostics. The switch also fails on MSBuild warnings, such as MSB3277 assembly version conflicts.- Enforce style the same way: run analyzers in the build, and run
dotnet format --verify-no-changesin a job of its own, beside the build job, as the example does. A formatting difference then reports in the time the check takes, not after the tests, and neither job's failure skips the other's steps. Meziantou's post runs the check as a separatelint_csharpjob, and uses the flag's earlier name,--check. (Meziantou: Enforce .NET code style in CI, Microsoft Learn: dotnet format, Meziantou: The Roslyn analyzers I use)
- Enforce style the same way: run analyzers in the build, and run
- Test. Run
dotnet teston Microsoft.Testing.Platform (MTP). MTP needs thetest.runneropt-in inglobal.json, as testing.md describes. Don't setDOTNET_TEST_RUNNERin the pipeline: on the .NET 11 SDK it overridesglobal.json, so CI could run a different runner from a developer's machine. "If neither setting selects a runner,dotnet testuses VSTest", which fails an xunit.v3 4.0.0 project on the .NET 10 SDK and later. (Microsoft Learn: dotnet test)- Upload TRX and coverage files as build artifacts, so you can diagnose a failure without a rerun.
- Under xunit.v3, write TRX with
--report-xunit-trxand--results-directory, as in the example.--coveragewrites the coverage file to the same directory, and needs theMicrosoft.Testing.Extensions.CodeCoveragepackage, which templates/projects/Example.Library.Tests.csproj references. Upload the results even when the step fails, because the failed run is the one you need them for. - MTP rejects VSTest's
--logger trx. For details, see testing.md.
- Publish or pack. Pass
--no-build, and upload the output as the one artifact that deploy and release consume. Never rebuild for deployment.- Don't pass
--output. With the artifacts layout from templates/Directory.Build.props, a single-TFM publish without a RID goes toartifacts/publish/<Project>/release. Otherwise, the last folder gets a_<tfm>or_<rid>suffix. Pack output goes toartifacts/package/<configuration>, with no project folder. For details, see project-structure.md. (Microsoft Learn: Artifacts output layout) - Keep test projects out of the deploy artifact with
<IsPublishable>false</IsPublishable>, as templates/projects/Example.Library.Tests.csproj does. Without it, a solution-level publish writes the test host, and another copy of every referenced library, intoartifacts/publish.
- Don't pass
The example uses GitHub Actions, but the stages work on any CI platform:
# Least privilege: unless the repository says otherwise, the default token can
# write to contents, and a build job doesn't need to.
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6
with:
global-json-file: global.json
- run: dotnet restore
- run: dotnet build --no-restore --configuration Release -warnaserror
- run: dotnet test --no-build --configuration Release --report-xunit-trx --coverage --coverage-output-format cobertura --results-directory artifacts/test-results
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
if: ${{ !cancelled() }}
with:
name: test-results
path: artifacts/test-results
- run: dotnet publish --no-build --configuration Release
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: app
path: artifacts/publish
# A job of its own, so a formatting difference reports without waiting for
# the tests, and a failed test doesn't skip the check.
format:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6
with:
global-json-file: global.json
- run: dotnet restore
- run: dotnet format --verify-no-changes --no-restore
# The build job uploads `app` whether or not the format check passes, so a
# job that deploys it waits for both.
# deploy:
# needs: [build, format]
This repository runs the checkout and setup-dotnet pins. The upload-artifact pin is only an example. When you copy the workflow, resolve every SHA against the current release, and check the major version. A pinned SHA never reports that it's out of date, so pair SHA pinning with a dependency bot.
In the build job, a failed step hides the results of the steps after it, wherever the check goes. A step runs only if every step before it succeeded: "A default status check of success() is applied" unless the step's if calls a status check function, such as !cancelled(). (GitHub Docs: Evaluate expressions in workflows and actions)
- A step before the build hides the test results when the formatting is wrong, so a push that breaks both needs a run for each.
- A step after the tests reports a formatting difference only when the tests finish, and not at all when a test fails.
The format job costs a second runner, and the app artifact no longer waits for the check.
- It repeats the setup. The job checks out the repository, installs the SDK, and restores again. It needs no build: after
dotnet restore,dotnet formatloads the solution itself, and "may restore, compile, and run analyzers". It can't reuse the build job's output, so the cost grows with the solution. (Microsoft Learn: dotnet format) - Gate the deploy and the merge on both jobs. The build job uploads the
appartifact whether or not theformatjob passes. A job that deploys it lists both inneeds, as the commenteddeployjob in the example does, so a failed check skips the deploy. Require bothbuildandformatas status checks on the branch: a rule that requires onlybuildmerges a formatting difference. (GitHub Docs: Workflow syntax for GitHub Actions, GitHub Docs: About protected branches)
Artifact signing
Spend your signing effort on provenance and credentials, not on author signing. For NuGet packages:
- Ship deterministic builds, with Source Link, symbols, and package validation enabled. (Meziantou: Publishing a NuGet package using GitHub Actions)
- Publish with trusted publishing, which leaves no credential in the repository. The workflow trades "a short-lived GitHub OIDC token to request a temporary, single-use NuGet API key", and "These keys expire quickly (≈ 1 hour)". That removes a secret whose "lifecycle... is notoriously difficult" to manage. (Tvorun and Iyer: New Trusted Publishing enhances security on NuGet.org, Lock: Publishing NuGet packages from GitHub actions the easy way with Trusted Publishing, Microsoft Learn: Trusted Publishing)
- If your CI host can't present an OIDC token, use a scoped API key stored as a repository secret, and name an owner to rotate it. nuget.org caps a new key at 30 days. (.NET Team: Strengthening NuGet Supply Chain Security: Reducing API Key Lifetime)
- Author-sign only if your organisation already runs certificate infrastructure. A package gets a signature without it: "all packages uploaded to nuget.org are automatically repository signed". (Microsoft Learn: Signed packages, Microsoft Learn: Sign a NuGet package)
Pinning protects consumers more than a signature does: locked restore, a pinned SDK, and SHA-pinned actions decide what goes into the package.
Don't add a signer allow list (signatureValidationMode set to require, with trustedSigners in nuget.config) unless you can maintain it. Each certificate rotation fails installs with NU3034 until you add the new SHA-256 fingerprint beside the old ones. Microsoft rotated its author-signing certificate from 2026-09-23. (.NET Blog: Microsoft is updating its author-signing certificate starting September 23, 2026)
Dependency updates
Use Renovate, with one shared configuration preset across every repository. A preset is "a named set of rules for updating dependencies" that each repository extends, so one change reaches all of them. Meziantou's preset pins GitHub Actions to digests with helpers:pinGitHubActionDigests, and a regex in the configuration updates .nuspec dependencies, which Renovate doesn't read by default. He finds Renovate "more configurable than Dependabot". (Meziantou: Sharing the Renovate configuration across multiple projects, Meziantou: Update dependencies in nuspec with Renovate) Renovate's nuget manager also updates the SDK version in global.json. (Renovate: NuGet manager)
Merge updates only through the pipeline above. An update that skips locked restore and tests is a supply-chain risk.
House opinion · Simon McKenna
House: Leave the bot's dependency dashboard issue open. Renovate manages it, and closing it doesn't opt out: the next run re-creates it under a new number and notifies everyone again.
- It's the only list of pending updates. Updates that
prConcurrentLimitdelays, or that a failing branch blocks, appear nowhere else. Its checkboxes trigger an off-schedule run without a configuration change. - It's where you approve gated updates. With
dependencyDashboardApprovalset, Renovate opens a pull request only after you tick the update's box on the dashboard. - Leave
dependencyDashboardAutocloseoff. It closes the issue whenever nothing is pending. A new issue every cycle costs more attention than one that stays open, and the closed issue hides a growing backlog. - If a stale-issue bot flags the dashboard, exempt it by label.
Two rules keep the dashboard useful as a repository grows:
- Don't use its list of detected dependencies as an audit record. GitHub caps an issue body at 65,536 characters, so Renovate trims the list in a large repository. Check what the bot manages in a configuration test or a scheduled dry run, where truncation fails visibly.
- Keep the pending list short, and give it an owner. People stop reading a dashboard with hundreds of open entries. Fix the cause in the grouping and scheduling policy: group related updates, widen the schedule until the queue clears, and name the team that works through it.