Designs and troubleshoots NUKE-based CI/CD pipelines for .NET services. Use when refactoring target graphs, splitting test flows, publishing reports, or diagnosing slow pipelines.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Designs and troubleshoots NUKE-based CI/CD pipelines for .NET services. Use when refactoring target graphs, splitting test flows, publishing reports, or diagnosing slow pipelines.
compatibility
Repo-local — NUKE .NET pipelines with repo-specific targets.
version
1.1
last_validated
2026-07-11T00:00:00.000Z
NUKE CI/CD
Quick Reference
Start from existing nuke/Build.cs targets and preserve output contracts before refactoring.
Keep target graph intent explicit: use DependsOn for hard prerequisites, After for ordering, Triggers for composed flows, and OnlyWhenDynamic for runtime gates.
Choose one repository test platform and keep it consistent across CI and local runs: VSTest or Microsoft.Testing.Platform.
If the repo uses .NET 10 Microsoft.Testing.Platform mode, do not assume VSTest-specific options such as --logger or collectors still apply.
Use this skill for pipeline orchestration and build contracts, not for application-service refactors or NUnit fixture internals.
Separate fast local feedback (build + filtered tests) from full CI validation (unit + api + db + merged coverage).
Run preflight checks before expensive targets: SDK version, Docker availability (when required), and expected file paths.
Prefer --artifacts-path when direct dotnet test runs need isolated output roots.
Use category filters intentionally, including exclusion filter patterns such as TestCategory!=ComponentTests&TestCategory!=DbTests&TestCategory!=ApiTest.
Keep UnitTest scoped to non-API categories and create a dedicated ApiTest target for TestCategory=ApiTest.
Keep TestAll composed from UnitTest + ApiTest (+ DbTest) and coverage merge.
When migrating from legacy docker-compose/SpecFlow orchestration, decommission compose-first test flow and keep pipeline focused on NUnit API categories.
Avoid running parallel dotnet test invocations against the same project output path in one job to prevent file-lock/MSBuild manifest failures.
Use dynamic host-port reservation for Docker-backed test infrastructure — no hard-coded localhost ports.
Resolve Docker host from Testcontainers API or DOCKER_HOST in CI — never assume localhost reaches containers.
Wire new test suites into the canonical pipeline entry point as part of feature delivery, not follow-up cleanup.
Keep shell commands robust for zsh: avoid unquoted globs in direct shell commands and validate paths before sed/cat/ls.
Emit coverage and test artifacts deterministically (coverage.cobertura.xml, HTML summary, JUnit XML).
Use Dockerfiles when the repo needs custom packaging or hardening; consider /t:PublishContainer for simpler SDK-native images.
When using /t:PublishContainer, set ContainerFamily=jammy-chiseled for chiseled images; non-root (UID 1654) and port 8080 are defaults since .NET 8 — do not assume port 80.
NUKE's DotNetTest helper is VSTest-oriented and does not support Microsoft.Testing.Platform (NUKE issue #1584, confirmed open, no maintainer commitment, as of 2026-07-11). VSTest remains the defaultdotnet test mode on .NET 10 — MTP mode is opt-in via a test.runner entry in global.json. Never assume a repo is on MTP just because it targets .NET 10; check global.json and project SDK settings first. Once a repo does opt in, drive MTP runners via ProcessTasks.StartProcess, not DotNetTasks.DotNetTest.
Generate SBOM as a first-class NUKE target (sbom-tool or CycloneDX .NET); attest NuGet/container artifacts with actions/attest-build-provenance; commit packages.lock.json and restore with RestoreLockedMode=true in CI.
NuGet signature verification is on by default since the .NET 8 SDK; run dotnet nuget verify as a preflight gate for produced .nupkg artifacts.
Publish digest-pinned image references into deploy.env or CI-native outputs, prefer structured digest outputs, and emit provenance/SBOM when supported.
Use IsLocalBuild only for performance and output-path concerns, not correctness.
If the task shifts into service implementation details, switch to $software-csharp-backend.
If the task shifts into fixture design, WireMock/Testcontainers setup, or anti-flake test structure, switch to $qa-testing-nunit.
When Not to Use This Skill
The repo does not use NUKE (plain MSBuild targets, Cake, PowerShell/Bash-only pipelines, or CI-native workflows with no build-automation layer) — this skill's target-graph, DotNetTasks, and NUKE-idiom guidance does not transfer; use $ops-devops-platform or $ops-platform-engineer instead.
The question is "should we adopt NUKE at all" rather than "how do we fix/extend our existing NUKE pipeline" — that is a build-tool selection decision (NUKE vs Cake vs raw MSBuild vs CI-native YAML), not something this skill's repo-local troubleshooting scope covers.
NUKE's GitHub Actions pipeline generation feature (nuke.build/docs/cicd/github-actions/) is used to scaffold the workflow YAML itself — that is a one-time generator invoked from the NUKE CLI, not a target-graph design question; treat generated YAML as a starting point to review, not a runtime behavior to debug with this skill's target-graph tools.
A failure is actually in NUnit fixture logic, WireMock stub setup, or test flakiness root-causing — hand off to $qa-testing-nunit rather than treating it as a pipeline/target problem.
MTP Migration Decision Framework
NUKE issue #1584 (open, unresolved as of 2026-07-11) means a repo cannot get first-class NUKE support for Microsoft.Testing.Platform today. Before recommending an MTP migration inside a NUKE pipeline, weigh:
Stay on VSTest if the repo has no immediate driver (no xUnit v3/TUnit adoption pressure, VSTest coverage/logger tooling works) — VSTest remains the default and best-supported path through NUKE's DotNetTest helper.
Migrate only if forced — e.g., a test framework upgrade (xUnit v3, TUnit) is MTP-only and unavoidable. In that case, accept the ProcessTasks.StartProcess workaround (see references/test-platform-modes-and-cli.md) as the interim pattern, and flag to the team that NUKE's fluent test helpers are not usable for that project until #1584 closes.
Do not partially migrate a solution — running some projects VSTest and others MTP inside one dotnet test invocation is explicitly unsupported by Microsoft's own docs; keep migration scoped to whole solutions or explicitly branch the NUKE target per project group.
Re-verify #1584's status before committing to either path on a long-lived project — this is exactly the kind of unresolved upstream issue that can close without notice; check it fresh rather than trusting a cached answer.
Workflow
Model or review target graph sequencing and execution constraints.
Load references/nuke-target-graph-design.md.
Design the build-test loop for early failures and rapid signal.
Load references/build-test-feedback-loop.md.
Lock repository test platform and CLI mode before changing reporting or runner arguments.
Load references/test-platform-modes-and-cli.md.
Define and verify test category filters for unit/API/DB/component separation.
Load references/test-categories-and-filters.md.
Implement coverage and test reporting with merge/publish outputs.
Load references/coverage-and-reporting.md.
Implement Docker build/push with tag + digest capture and deployment outputs.
Load references/docker-build-push-patterns.md.
Enforce stable artifact contracts and CI/provider output exports.
Load references/ci-output-contracts-and-provenance.md.
Tune local vs CI behavior without hiding pipeline defects.
Load references/local-vs-ci-behavior.md.
Harden reliability, logs, and diagnostics for CI incident response.
Load references/pipeline-reliability-and-observability.md.
Run command hygiene and environment preflight checks before final run.
Load references/execution-preflight-and-command-hygiene.md.
Run anti-pattern review before finalizing.
Load references/nuke-pipeline-antipatterns.md.
ASCII Flow
NUKE pipeline request or failure
-> Inspect existing Build.cs targets and CI entry points
-> Model target graph: DependsOn, After, Triggers, runtime gates
-> Lock test platform and category contract
+-- fast local -> build plus filtered tests
+-- full CI -> unit plus API/DB/component plus merged coverage
-> Stabilize artifacts: JUnit, coverage, HTML, env outputs, digest
-> Harden Docker and external-service behavior when present
-> Run preflight checks for SDK, Docker, paths, shell quoting, and CI env
-> Execute canonical target and inspect logs before final guidance
Decision Tree
If target ordering is incorrect or unexpected targets run, use references/nuke-target-graph-design.md.
If feedback loop is too slow or flaky, use references/build-test-feedback-loop.md.
If the repo is moving to .NET 10 test flows, MTP, or mixed runner behavior is suspected, use references/test-platform-modes-and-cli.md.
If test scope is wrong in CI or local runs, use references/test-categories-and-filters.md.
If coverage or JUnit artifacts are missing/partial, use references/coverage-and-reporting.md.
If Docker outputs are not traceable or digest pinning is missing, use references/docker-build-push-patterns.md.
If downstream jobs cannot consume artifacts, env outputs, or provenance metadata, use references/ci-output-contracts-and-provenance.md.
If local and CI behavior diverge unexpectedly, use references/local-vs-ci-behavior.md.
If failures are hard to debug from logs, use references/pipeline-reliability-and-observability.md.
If failures come from shell quoting, glob expansion, missing files, or environment prerequisites, use references/execution-preflight-and-command-hygiene.md.
If pipeline quality regresses during refactors, use references/nuke-pipeline-antipatterns.md.
If Docker-backed tests pass locally but fail in CI, use references/local-vs-ci-behavior.md + references/execution-preflight-and-command-hygiene.md.
If a new test suite exists but is not running in CI, use references/nuke-target-graph-design.md.
Use at PR review time to verify that target graph, test platform, coverage, Docker, provenance, and artifact contracts are intact.
Fact-Checking
Verify current .NET test-platform behavior, NUKE package semantics, and CI-provider artifact/output conventions before final guidance.
Treat repo-local target names and category filters as local contracts, not generic NUKE defaults.
If web access is unavailable, mark version-sensitive CLI or provider guidance as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
