ops-nuke-cicd

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 default dotnet 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

1. Model or review target graph sequencing and execution constraints. Load references/nuke-target-graph-design.md.
2. Design the build-test loop for early failures and rapid signal. Load references/build-test-feedback-loop.md.
3. Lock repository test platform and CLI mode before changing reporting or runner arguments. Load references/test-platform-modes-and-cli.md.
4. Define and verify test category filters for unit/API/DB/component separation. Load references/test-categories-and-filters.md.
5. Implement coverage and test reporting with merge/publish outputs. Load references/coverage-and-reporting.md.
6. Implement Docker build/push with tag + digest capture and deployment outputs. Load references/docker-build-push-patterns.md.
7. Enforce stable artifact contracts and CI/provider output exports. Load references/ci-output-contracts-and-provenance.md.
8. Tune local vs CI behavior without hiding pipeline defects. Load references/local-vs-ci-behavior.md.
9. Harden reliability, logs, and diagnostics for CI incident response. Load references/pipeline-reliability-and-observability.md.
10. Run command hygiene and environment preflight checks before final run. Load references/execution-preflight-and-command-hygiene.md.
11. 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.

Symptom → Reference

Do / Avoid

Do

• Keep targets deterministic and side effects explicit.
• Keep test stages isolated by category and risk profile.
• Keep coverage/report merge as a first-class target in the graph.
• Keep Docker outputs traceable through tag, digest, and exported env variables.
• Keep artifact paths and names stable across branches and CI systems.

Avoid

• Mixing orchestration and hidden side effects inside unrelated targets.
• Running expensive integration tests before compile/unit gates.
• Changing output file names without updating consumer jobs.
• Using local-only shortcuts that invalidate CI parity.
• Ignoring digest capture and shipping mutable image references.

Navigation

• NUKE Target Graph Design
• Build-Test Feedback Loop
• Test Platform Modes and CLI
• Test Categories and Filters
• Coverage and Reporting
• Docker Build Push Patterns
• CI Output Contracts and Provenance
• Local vs CI Behavior
• Pipeline Reliability and Observability
• Execution Preflight and Command Hygiene
• NUKE Pipeline Antipatterns
• Skill Sources: curated official NUKE, .NET, container, and CI references for this skill.

Assets

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.