tfnotify配置文件完整参考tfnotify.yaml所有字段详解附JSON Schema校验支持【免费下载链接】tfnotifyA CLI command to parse Terraform execution result and notify it to GitHub项目地址: https://gitcode.com/gh_mirrors/tf/tfnotifytfnotify 是一个开源 CLI 工具用于解析 Terraformplan/apply的执行结果并以评论形式发布到 GitHub PR、Issue 或 Commit。而一切行为都由tfnotify 配置文件tfnotify.yaml驱动。本文带你完整过一遍tfnotify.yaml的所有字段并介绍如何通过 JSON Schema 做配置校验帮你一次写对、少走弯路。一、tfnotify 如何找到配置文件tfnotify 启动时按以下顺序查找配置--config参数显式指定路径对应环境变量TFNOTIFY_CONFIG未指定时自动在目录下搜索tfnotify.yaml→tfnotify.yml→.tfnotify.yaml→.tfnotify.yml查找逻辑实现在 pkg/config/config.go 的Find方法中。因此大多数场景下你只要把tfnotify.yaml放在项目根目录即可。二、配置文件顶层结构一览字段类型说明terraformobject核心配置plan/apply 的模板与条件标签 slackobjectSlack 通知开关与消息模板ai_summaryobjectAI 摘要生成配置可选embedded_var_namesstring[]允许通过--var注入的模板变量名白名单templatesmap额外的具名模板供其他模板引用logobject日志级别level字段ghe_base_urlstringGitHub Enterprise REST API 地址ghe_graphql_endpointstringGitHub Enterprise GraphQL 端点plan_patchbool默认对 plan 评论做更新已有评论而非新建repo_owner/repo_namestringGitHub 仓库所有者与名称三、terraform 段详解最常用3.1 terraform.plan —— plan 结果处理字段说明templateGo template 模板决定 plan 评论内容when_add_or_update_onlyplan 仅含新增/更新时触发见 3.3when_destroyplan 含资源删除时触发可加警告评论和标签when_no_changes无变更时触发可打标并可disable_comment跳过评论when_plan_errorplan 执行失败时打标when_parse_error输出解析失败时使用的备用模板disable_label关闭该次 plan 的标签更新ignore_warning忽略 Terraform 输出的 warning3.2 terraform.apply —— apply 结果处理字段说明templateapply 评论模板when_parse_error解析失败时的备用模板template字段3.3 条件标签三兄弟label / label_color / disable_labelwhen_add_or_update_only、when_destroy、when_no_changes、when_plan_error均支持以下子字段label要打到 PR 上的标签名如destroy、no-changeslabel_color标签颜色disable_label仅在该条件下关闭打标一个典型组合可参考项目自带的 example-with-destroy-and-result-labels.tfnotify.yamlterraform: plan: template: | {{if .HasDestroy}} ## :warning: Resource Deletion will happen {{else}} ## Plan Result {{ .Result }} {{end}} when_add_or_update_only: label: add-or-update when_destroy: label: destroy when_no_changes: label: no-changes when_plan_error: label: error3.4 输出相关开关字段说明use_raw_outputtrue时不对 Terraform 输出做 HTML 转义适合直接放进代码块见 example-use-raw-output.tfnotify.yamlconsolidatedTerragrunt 场景下把所有模块结果合并为一条评论而不是每个模块一条3.5 模板可用变量速查模板中支持以下占位符Go text/template 语法占位符含义{{ .Title }}标题如## Plan Result{{ .Message }}通过 CLI--message传入的自定义消息{{ .Result }}解析出的关键结果如Plan: 1 to add、No changes{{ .Body }}/{{ .CombinedOutput }}Terraform 完整执行输出{{ .Link }}CI 构建页面链接{{ .HasDestroy }}布尔值plan 是否含删除操作{{ .Vars.name }}通过--var name:value传入的自定义变量项目内置的默认模板存放在 templates/ 目录default.md、plan-success.md、apply-failure.md等可作为自定义模板的起点。四、slack 段Slack 通知配置 字段说明enabled是否启用 Slack 通知title/message默认标题与正文模板plan_title/plan_messageplan 通知专用模板apply_title/apply_messageapply 通知专用模板notify_on_plan_error/notify_on_apply_error失败时也发送通知use_threads错误详情以线程回复形式发送注意Slack 的token、channel_id、bot_name不写在配置文件中而是分别从环境变量SLACK_BOT_TOKEN、SLACK_CHANNEL_ID、SLACK_BOT_NAME读取避免凭据入库。五、ai_summary 段AI 摘要生成 字段说明enabled是否启用 AI 摘要provider提供商litellm默认、openai、anthropic、google、devinmodel使用的模型名Devin 提供商下无效template/template_file自定义 prompt 模板内联或文件路径max_tokens摘要最大 token 数各提供商实现分别位于pkg/ai/目录anthropic.go、openai.go、litellm.go、devin.go。六、敏感信息掩码maskstfnotify 支持对评论中的敏感字符串做掩码但不通过 yaml 配置而是通过环境变量TFNOTIFY_MASKS格式为类型:值多条用TFNOTIFY_MASKS_SEPARATOR默认逗号分隔env:SECRET_KEY—— 掩码该环境变量的值regexp:sk-[a-z0-9]—— 掩码匹配正则的文本解析逻辑见 pkg/mask/parser.go。七、JSON Schema 校验支持 ✅项目内置了一份官方 JSON Schemajson-schema/tfnotify.json基于 draft 2020-12并对所有顶层与嵌套结构启用了additionalProperties: false——拼错字段名会直接被校验拦截这对新手特别友好。几个实用要点编辑器校验在支持 JSON Schema 的编辑器中引用该 schema 文件即可获得tfnotify.yaml字段的补全与报错提示字段以 schema 为准terraform段在 schema 中明确了plan、apply、use_raw_output三个属性其余属性均不允许自动同步schema 由 cmd/gen-jsonschema/main.go 基于 pkg/config/config.go 的结构体定义自动生成保证与代码实现一致八、CLI 参数与配置文件的配合很多字段同时提供 CLI 参数与环境变量优先级通常高于配置文件功能CLI 参数环境变量仓库信息--owner/--repo/--sha/--prTFNOTIFY_REPO_OWNER等配置路径--configTFNOTIFY_CONFIG更新已有评论plan --patchTFNOTIFY_PLAN_PATCH无变更时跳过评论plan --skip-no-changesTFNOTIFY_SKIP_NO_CHANGESAI 摘要--summary/--summary-provider/--summary-modelTFNOTIFY_AI_SUMMARY等输出到文件--output—自定义模板变量--var name:value—参数定义见 pkg/cli/app.go。一个常用姿势terraform plan | tfnotify plan管道喂入 Terraform 输出即可完成解析与通知。九、总结最常用的是terraform.plan.template与when_*条件标签覆盖 90% 场景Slack 凭据走环境变量敏感数据用TFNOTIFY_MASKS掩码配置文件可放心入库写配置时挂上 json-schema/tfnotify.json拼写错误当场可见完整可运行示例请直接参考仓库根目录的 example.tfnotify.yaml结合上文字段表即可快速定制出你自己的 tfnotify 配置文件。【免费下载链接】tfnotifyA CLI command to parse Terraform execution result and notify it to GitHub项目地址: https://gitcode.com/gh_mirrors/tf/tfnotify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考