GitHub Actions YAML文件是纯文本，C#生成只需字符串或模板，无需SDK；关键在于路径正确（.github/workflows/*.yml）、命名规范、避免空格缩进错误、防止自触发循环，并确保语义准确。
GitHub Actions YAML 文件本质就是纯文本，C# 生成它不靠 SDK，只靠字符串或模板
GitHub 不提供官方 C# SDK 来“创建工作流”，.github/workflows/ci.yml 就是个普通 YAML 文件，放在仓库里就被自动识别。C# 能做的只有：生成内容、写入文件、提交到 Git —— 全程不涉及 API 调用或认证。
常见错误是试图找 GithubActionsSdk 或调用 CreateWorkflowAsync 这类根本不存在的 API；也有人误以为要用 Octokit.NET 提交 YAML，其实 Octokit 只负责 Git 操作，YAML 内容还得自己拼。
- 最轻量做法：用
System.Text.Json或匿名对象 +YamlDotNet序列化成 YAML（但要注意键名大小写和缩进） - 更稳的做法：用字符串插值或
EmbeddedResource模板 +string.Replace()填充变量（比如{% raw %}{{branch}}{% endraw %}） - 避免直接拼接 YAML 的 key：像
"on:\n push:\n branches: [main]"容易错缩进，YAML 对空格敏感，一个空格错就导致 workflow 不触发
用 YamlDotNet 序列化 C# 对象时，必须配置 EmitDefaults 和 IgnoreFields
YAML 和 JSON 不同，null 字段、默认值、字段顺序都会影响语义。比如 if: ${{ always() }} 是合法条件，但序列化出 if: null 就会报错 The pipeline is not valid. .github/workflows/ci.yml (Line: X, Col: Y): Unexpected value 'null'。
典型问题场景：你定义了一个 Job 类，其中 Steps 是 List<Step>，但没给 Step 的 With 属性赋值（它是 Dictionary<string, object>），序列化后变成 with: null，CI 直接失败。
- 必须设置
SerializerSettings.DefaultValuesHandling = DefaultValuesHandling.Ignore - 加上
SerializerSettings.IgnoreFields = true，否则私有字段可能被意外写出 - 用
[YamlMember(Alias = "run")]显式控制 key 名，别依赖属性名自动转小写 - 别让
object类型字段存函数表达式字符串（如"${{ matrix.os }}"），YamlDotNet 会把它当字典或数组解析，得用YamlScalarNode手动构造
动态生成的 workflow 文件必须满足 GitHub 的路径和命名硬约束
GitHub 只认 .github/workflows/xxx.yml（或 .yml，不支持 .yaml），且文件名不能含大写字母、空格、下划线（推荐全小写 + 短横线），否则在 UI 上不显示，git status 看得到，但 Actions 标签页里找不到。
容易踩的坑是本地测试时路径写成 ./workflows/ci.yml 或 .github/workflows/CI.yml，结果推送后 workflow 完全不触发，日志里连 “skipped” 都没有 —— 因为压根没被扫描到。
- 路径必须是
.github/workflows/<lowercase-dash-separated>.yml - 文件内容开头必须有
name:字段（非必需但强烈建议），否则 GitHub UI 显示为空白名称 - 如果用 C# 自动生成多个 workflow（如 per-branch 或 per-feature），注意不要覆盖已有文件，可用
File.Exists()+ 时间戳后缀规避冲突 - 生成完记得
git add .github/workflows/，否则 CI 不生效 —— 这步常被忽略，尤其在 CI 中自动生成 workflow 的场景
在 GitHub Actions 自身流程里用 C# 生成 workflow，要防循环触发
如果你的 workflow 任务里运行 C# 程序去生成新的 .github/workflows/xxx.yml 并自动提交，那这个提交会再次触发 workflow —— 默认情况下，所有 push 都会触发，包括 bot 提交。
典型现象：一次 PR 触发构建 → C# 生成新 workflow → 推送 commit → 新 commit 又触发构建 → 无限循环，仓库里堆满重复提交。
- 在 push 的
workflow_dispatch或pull_request触发器里加if: github.actor != 'github-actions[bot]'过滤 bot 提交 - 或者改用
paths-ignore：在顶层on:下写paths-ignore: [".github/workflows/**"]，但注意这会跳过所有 workflow 文件变更的触发，慎用 - 更干净的做法：生成 workflow 后不自动 push，而是输出 diff 到日志，人工审核后手动合并 —— 尤其对生产环境 workflow
- 调试阶段可在 C# 里加
Console.WriteLine($"Generated: {filePath}")，配合actions/checkout@v4的fetch-depth: 0才能正确 git commit
真正麻烦的不是生成 YAML，而是确保它被放对位置、叫对名字、不引发自触发、且每次生成的内容语义准确 —— 这些细节比语法本身更消耗调试时间。
