ops-nuke-cicd

NUKE CI/CD

快速参考

• 从仓库现有的 NUKE Build.cs 目标入手，在重构前保留输出契约。
• 明确目标图的意图：使用 DependsOn 表示硬性前置条件，使用 After 控制顺序，使用 Triggers 组合流程，使用 OnlyWhenDynamic 设置运行时门控。
• 为仓库选择一种测试平台，并在 CI 和本地运行中保持一致：VSTest 或 Microsoft.Testing.Platform。
• 将此技能用于管道编排和构建契约，而非应用服务重构或 NUnit 夹具内部实现。
• 将快速本地反馈（build + filtered tests）与完整 CI 验证（unit + api + db + merged coverage）分开。
• 在运行耗时较长的目标前执行预检：SDK 版本、Docker 是否可用（如有需要）以及预期文件路径。
• 直接运行 dotnet test 需要隔离输出根目录时，优先使用 --artifacts-path。
• 为每种测试类别指定一个目标和一个筛选器。将类别名称集中在一处（例如常量类中），统一所有类别的命名风格，并确保单元测试目标排除所有非单元测试类别。
• 在构建、所有类别目标和覆盖率合并目标之上设置一个组合式 CI 目标（例如 TestAll）。替换旧版测试编排路径时，应移除其目标和环境配置，不要将其闲置保留。
• 避免在同一个作业中针对同一项目输出路径并行运行多个 dotnet test，以防文件锁定或 MSBuild 清单错误。
• Docker 支持的测试基础设施应动态预留主机端口，不要硬编码 localhost 端口。
• 在 CI 中通过 Testcontainers API 或 DOCKER_HOST 解析 Docker 主机，切勿假定 localhost 可以访问容器。
• 交付功能时，应将新的测试套件接入规范管道入口，不要留待后续清理。
• 保持 shell 命令兼容 zsh：在直接 shell 命令中避免使用未加引号的通配符，并在运行 sed/cat/ls 前验证路径。
• 以确定的方式生成覆盖率和测试产物（coverage.cobertura.xml、HTML 摘要、JUnit XML）。
• 仓库需要自定义打包或加固时使用 Dockerfile；对于更简单的 SDK 原生镜像，可考虑 /t:PublishContainer。
• 使用 /t:PublishContainer 时，将 ContainerFamily 设置为与基础镜像匹配的精简容器系列；从 .NET 8 起，默认使用非 root 用户（UID 1654）和端口 8080，不要假设端口为 80。
• NUKE issue #1584 跟踪了 DotNetTest 对 Microsoft.Testing.Platform 的支持情况；选择变通方案前，请检查该 issue 和当前辅助 API。在 MTP 模式下，--logger 和数据收集器等 VSTest 专用选项不适用。在 .NET 10 上，VSTest 仍是 dotnet test 的默认模式。选择运行器参数前，请检查 global.json、已安装 SDK 支持的任何运行器覆盖设置，以及项目 SDK 设置；仅面向 .NET 10 并不会启用 MTP。如果 NUKE 辅助工具仍不支持 MTP，请通过 ProcessTasks.StartProcess 调用运行器。
• 将 SBOM 生成为 NUKE 的一等目标（使用 sbom-tool 或 CycloneDX .NET）；使用 actions/attest-build-provenance 为 NuGet/容器产物生成证明；将 packages.lock.json 提交到仓库，并在 CI 中设置 RestoreLockedMode=true 进行还原。
• 自 .NET 8 SDK 起，默认启用 NuGet 签名验证；对生成的 .nupkg 产物运行 dotnet nuget verify，将其作为预检门槛。
• 将固定摘要的镜像引用写入 deploy.env 或 CI 原生输出；优先使用结构化摘要输出，并在支持时生成来源证明/SBOM。
• IsLocalBuild 仅用于性能和输出路径相关问题，不用于正确性控制。
• 如果任务转向服务实现细节，请切换到 $software-csharp-backend。
• 如果任务转向夹具设计、WireMock/Testcontainers 设置或防抖测试结构，请切换到 $qa-testing-nunit。

何时不应使用此技能

• 仓库未使用 NUKE（例如纯 MSBuild 目标、Cake、仅使用 PowerShell/Bash 的流水线，或没有构建自动化层的 CI 原生工作流）——此技能关于目标图、DotNetTasks 和 NUKE 惯用法的指导不适用；请改用 $ops-devops-platform。
• 问题是“是否应该采用 NUKE”，而不是“如何修复/扩展现有 NUKE 流水线”——这是构建工具选型问题（NUKE、Cake、原生 MSBuild 或 CI 原生 YAML），不在此技能的故障排查范围内。
• 使用了 NUKE 的 GitHub Actions 流水线生成功能（nuke.build/docs/cicd/github-actions/）来搭建工作流 YAML 本身——这是通过 NUKE CLI 调用的一次性生成器，不是目标图设计问题；应将生成的 YAML 视为待审查的起点，而不是使用此技能的目标图工具来调试运行时行为。
• 故障实际出在 NUnit 固件逻辑、WireMock 模拟设置或测试不稳定问题的根因分析上——应交由 $qa-testing-nunit 处理，而不是将其视为流水线/目标问题。

MTP 迁移决策框架

在建议在 NUKE 流水线中迁移到 MTP 之前，请检查 NUKE issue #1584 和已安装的辅助 API。然后权衡以下因素：

• 继续使用 VSTest：如果 VSTest 覆盖率/日志记录工具能满足仓库需求，且测试框架支持该适配器。xUnit v3 可通过 xunit.runner.visualstudio 支持 VSTest；仅升级到 v3 并不意味着必须迁移到 MTP。
• 在所选框架要求使用 MTP 时迁移，例如 TUnit；或者在有实测收益的情况下迁移。如果已安装的 NUKE 辅助工具仍不支持 MTP，请使用 ProcessTasks.StartProcess 变通方案（参见 references/test-platform-modes-and-cli.md），并记录这一限制。
• 不要只迁移解决方案的一部分——微软官方文档明确指出，在一次 dotnet test 调用中让部分项目使用 VSTest、其他项目使用 MTP 不受支持；迁移应以整个解决方案为范围，或在 NUKE 目标中针对不同项目组进行明确分支。
• 在长期维护的项目中选定任一路径之前，重新确认 #1584 的状态和辅助工具的行为。

工作流

1. 建模或审查目标图的顺序和执行约束。 加载 references/nuke-target-graph-design.md。

2. 设计构建-测试循环，以便尽早发现失败并快速获取反馈。 加载 references/build-test-feedback-loop.md。

3. 在更改报告或运行器参数之前，锁定仓库的测试平台和 CLI 模式。 加载 references/test-platform-modes-and-cli.md。

4. 定义并验证测试类别筛选条件，以区分单元测试/API/DB/组件测试。 加载 references/test-categories-and-filters.md。

5. 实现覆盖率和测试报告，并合并/发布输出。 加载 references/coverage-and-reporting.md。

6. 实现 Docker 构建/推送，并捕获标签和摘要以及部署输出。 加载 references/docker-build-push-patterns.md。

7. 确保产物契约稳定，并导出 CI/提供商输出。 加载 references/ci-output-contracts-and-provenance.md。

8. 调整本地与 CI 行为，但不要掩盖流水线缺陷。 加载 references/local-vs-ci-behavior.md。

9. 加强可靠性、日志和诊断能力，以便响应 CI 事故。 加载 references/pipeline-reliability-and-observability.md。

10. 最终运行前，检查命令规范并执行环境预检。 加载 references/execution-preflight-and-command-hygiene.md。

11. 最终确定前，检查反模式。 加载 references/nuke-pipeline-antipatterns.md。

12. 在对应阶段验证每项流水线声明：从执行计划或目标日志确认目标选择；通过退出代码及测试/构建输出确认命令执行；通过收集器或部署作业读取确切的产物路径、摘要或导出变量，确认下游消费。编译 Build.cs 或检查 DependsOn 只能证明图的语法正确。如果 Docker、凭据或 CI 提供商不可用，应将相应阶段报告为未执行，并注明仍未执行的确切规范目标。

症状 → 参考资料

症状	主要参考资料	次要参考资料
测试在本地通过，在 CI 中失败	references/local-vs-ci-behavior.md	references/execution-preflight-and-command-hygiene.md
基于 Docker 的测试在本地通过，在 CI 中失败	references/local-vs-ci-behavior.md	references/execution-preflight-and-command-hygiene.md
流水线或反馈循环缓慢、不稳定或停滞	references/nuke-target-graph-design.md	references/build-test-feedback-loop.md
运行的测试不正确（过多或过少）	references/test-categories-and-filters.md	references/nuke-target-graph-design.md
缺少覆盖率或 JUnit 产物 / 产物不完整	references/coverage-and-reporting.md	references/ci-output-contracts-and-provenance.md
目标顺序意外或目标被跳过	references/nuke-target-graph-design.md	references/nuke-pipeline-antipatterns.md
.NET 10 / MTP 迁移后 dotnet test 参数失效，或怀疑存在混合运行器行为	references/test-platform-modes-and-cli.md	references/coverage-and-reporting.md
缺少摘要，或将可变镜像标签交付给部署	references/docker-build-push-patterns.md	references/ci-output-contracts-and-provenance.md
下游作业无法读取产物或 deploy.env	references/ci-output-contracts-and-provenance.md	references/local-vs-ci-behavior.md
难以根据 CI 日志诊断失败	references/pipeline-reliability-and-observability.md	references/execution-preflight-and-command-hygiene.md
Shell 引号 / glob / 缺少文件错误	references/execution-preflight-and-command-hygiene.md	—
新测试套件未在 CI 中运行	references/nuke-target-graph-design.md	references/nuke-pipeline-antipatterns.md
重构期间流水线质量退化	references/nuke-pipeline-antipatterns.md	references/build-test-feedback-loop.md

导航

• NUKE 目标图设计
• 构建-测试反馈循环
• 测试平台模式和 CLI
• 测试类别和筛选器
• 覆盖率和报告
• Docker 构建和推送模式
• CI 输出约定和来源信息
• 本地与 CI 行为
• 流水线可靠性和可观测性
• 执行预检和命令规范
• NUKE 流水线反模式
• 技能来源：为此技能精选的官方 NUKE、.NET、容器和 CI 参考资料。

资源

资源	使用时机
NUKE 目标模板：构建和测试	在搭建或重构构建、按类别测试和组合测试目标时，将其作为起点；这些目标使用一个类别列表、筛选器和覆盖率收集。目标和类别名称仅作示例。
NUKE 目标模板：Docker 构建、推送和摘要	在实现 Docker 镜像构建、标记、推送和摘要捕获目标，并生成部署引用时，将其作为起点。
测试结果和覆盖率发布检查清单	在最终确定任何覆盖率或测试报告变更之前使用，以确认所有输出路径、格式和 CI 收集器配置保持同步。
CI 故障排查检查清单	在 CI 故障期间使用，依次排查目标图、测试平台、Docker、工件和详细程度诊断。
PR 流水线质量检查清单	在 PR 审查时使用，以确认目标图、测试平台、覆盖率、Docker、来源信息和工件约定均保持完整。

经验总结循环

当先前的决策或陷阱与当前情况相关时，请查阅 learnings.consolidated.md（如果存在）；仅在需要了解历史或将其作为可用的后备资料时，才使用 learnings.md。否则跳过这两个文件。

应用后，如果遇到值得记住的模式、值得防范的错误或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目。不要修改 SKILL.md 本身。