Release failure notification

Release failure notification 指一个仓库为所有“预期成功但最终以 failure 结束”的交付 workflow 建立显式、可审查的告警路径。范围包括 release、deploy、CI、Docs Pages 和 required gate，但必须由 checked-in allowlist 声明；成功、skipped、cancelled 和通知 workflow 自身不属于通知条件。典型形态是一个很薄的 workflow_run sidecar：它监听声明过的 workflow，解析足够的 run metadata 来定位失败 commit 或 PR，再交给已被该项目选定的 delivery。它不是 GitHub 默认邮件通知，不是把 delivery 凭据硬塞进每个 publish job，也不是手工 checklist。这个 Topic 的合同是 sidecar、metadata、失败上下文与 workflow 分类；transport、外部 notifier、secret 名称和渠道不属于默认值（projects/blog-26.md、projects/flux-purr.md、projects/dockrev.md）。

这个 Topic 也暗含一个安全边界：任何带 secret 的通知 workflow 都不应执行 caller repository code。若项目已选择 reusable workflow，它只应接收 metadata、格式化 payload、调用 delivery action，而不是 checkout 调用方代码后再发送消息。对 release workflow 可以保留 identity-aware 专用 payload；对普通 expected-success workflow 应使用 metadata-only generic payload，不能伪造版本、tag 或 same-SHA recovery。

当 repo 有自动 release、deploy、image publish、Pages publish、CI 或其他 required gate，并且失败不应依赖人去轮询 GitHub Actions 时，应使用这个 Topic。它尤其适用于 label-driven 或 queued release，也适用于 Docs Pages/CI 等没有 release identity 但仍然预期成功的 workflow；前者保留 PR intent、commit SHA、component、channel、run attempt，后者至少保留 workflow、event、ref/branch、head SHA、PR、run ID、run attempt、actor 和 run URL（projects/blog-26.md、projects/flux-purr.md、projects/codex-vibe-monitor.md、projects/dockrev.md）。

当 release decision 来自 PR labels 时，通常应与 PR label release 一起使用。发布失败通知需要带上产生 release intent 的同一组上下文，否则 maintainer 只能看到“release failed”，却不知道是哪个 component/channel/bump 出错（projects/flux-purr.md、projects/xp.md）。

对使用 PR-local VERSION 发布链路的产品，通知还必须区分真正的 publish/deploy failure 与成功的 non-product skip。一个 release failure payload 应绑定已锁定的 VERSION、merged main SHA 与 recovery target；若 tag 已可确定，也应一并带上。type:docs / type:skip 令 release workflow 成功 skip 时，不应触发失败通知；只有实际的 failure conclusion 才进入本 Topic（projects/flux-purr.md、topics/pr-label-release.md、projects/dockrev.md）。

不要仅因为 repo 有 GitHub Actions 或发现一个跨仓库 reference 就套用这个 Topic。普通 CI workflow 加 GitHub 默认通知不够；项目必须有明确命名的 notification workflow，或有等价的 checked-in delivery contract（skills/style-playbook/references/data/topics/release-failure-notification.json）。

• notifier 应作为 sidecar workflow 存在，由 workflow_run 或 workflow_dispatch 触发。Release workflow 负责 build、versioning、signing、upload、publish；notifier workflow 负责上下文格式化与 alert delivery（projects/blog-26.md、projects/flux-purr.md）。
• 把 expected-success workflow 写入 checked-in allowlist，并把每个 top-level workflow name 精确归类为 generic、Release-specific 或 excluded；contract test 应在新增 workflow 未分类、通知 workflow 漏排除或 route 漂移时失败。Dockrev 的 .github/release-failure-notification.json 与 .github/scripts/test_workflow_failure_notification_contract.py 是直接样本（projects/dockrev.md）。
• generic sidecar 只订阅 allowlist 中的 workflow，并在 job 内显式 guard workflow_run.conclusion == failure；Release 继续走 identity-aware sidecar，避免同一失败重复通知或把 ordinary failure 描述成发布失败（projects/dockrev.md）。
• 只有项目证据证明多个调用方已经选择相同 transport 时，才可把 secret-using delivery 集中到 reusable workflow。共享实现不建立调用方的 transport 选择。
• 带 secret 的 notifier 不应 checkout 或执行不可信 caller code。任何共享 workflow 的价值都在于它只接收 metadata 和已选定的 secret，再发送消息。
• 通知 payload 要保存失败上下文，而不是只写 "release failed"。有用字段包括 repository、workflow name、conclusion、run URL、ref label、head SHA、run attempt、actor、event name，以及 manual dispatch 更改 target SHA 时从 logs 解析出来的 extra details（projects/blog-26.md）。
• generic workflow payload 至少要有 repository、workflow、event、ref/branch、head SHA、PR、run ID、run attempt、actor 和 run URL，并提供检查失败 job 后再重跑的 recovery guidance；它不应生成版本或 tag 结论（projects/dockrev.md）。
• PR-local VERSION 发布链路的 payload 还应带 VERSION、merged main SHA 与 recovery operation；tag 已确定时一并带上，避免维护者把同一锁定版本误当作下一版本重发（projects/flux-purr.md、topics/pr-label-release.md）。
• 已选定 transport 后保留 workflow_dispatch smoke test。通知链路是基础设施；配置迁移或 delivery 变更后，需要便宜的人工验证路径（projects/kaisoumail.md）。
• 缺少已选定 transport 的配置应作为错误显式暴露，而不是静默跳过通知。Delivery workflow 应明确 configuration owner、required secrets 和 permissions。

• 从 skills/policies/release-failure-notification/assets/templates/release-failure-notification-transport-gate.example.json 开始。该 gate 要求在 rollout 前记录项目既有合同，或记录主人明确选择；reference library 不能单独作为选择证据。
• 在选择证据缺失时，阻断 notifier rollout：不得新增外部 notifier、secret 或渠道，也不得以静默 skip 伪装为已配置通知。
• 选择完成后，记录 transport owner、configuration owner 和 required secrets；选定配置缺失时必须 fail closed，并让 notifier run 显式失败。

• 当前 Playbook 没有默认 transport 或默认 reusable notifier。任何新的 reference implementation 必须先有项目选型证据，不能由组织级 workflow 或历史样例反推。
• blog-26、kaisoumail 与 flux-purr 可用于复核 sidecar 的事件过滤、payload 与 release identity；它们不选择调用方的 transport（projects/blog-26.md、projects/kaisoumail.md、projects/flux-purr.md）。
• dockrev：.github/release-failure-notification.json 维护 expected-success allowlist；Notify failed release 保留 Release identity/same-SHA recovery，Notify failed workflow 覆盖 CI (PR)、Docs Pages、Release completion、Release Preparation 和 Review Policy，并从默认分支 checkout trusted helper（projects/dockrev.md）。

• 把 chat delivery 直接嵌进 release workflow，会让 release YAML 更难审查，也可能让通知失败被 publish 失败掩盖。优先使用围绕 failed run metadata 的 sidecar workflow（projects/blog-26.md）。
• 使用 workflow_run 却不检查 conclusion、branch、event、repository，会制造噪音或安全问题。Caller workflow 应显式 guard failure conclusion 和 same-repository release run（projects/blog-26.md）。
• 在 secret-bearing notifier 中执行 caller code 会扩大信任边界。Reusable notifier 只应格式化 metadata 并调用 delivery action，不应 clone caller repo。
• Alert payload 缺少 commit SHA、run URL、actor 时，排查会很慢。Actions UI 积累很多 runs 后，通知必须能让 maintainer 直接跳到失败 run（projects/blog-26.md）。
• 把 manual dispatch 当成普通 workflow_run 处理，可能报告错误 target SHA。若支持 backfill，应从 workflow inputs 或 logs 中解析真实 release target（projects/blog-26.md）。
• 将 successful skip 视为失败，会制造噪音并掩盖真实 publish/deploy failure。对于 PR-local VERSION 发布链路，应只通知失败的 release，并显示可 recovery 的同一 main identity（topics/pr-label-release.md）。
• 只把 Release 或某一个 Docs workflow 放进通知范围，会漏掉其他已经声明为 expected-success 的 CI、gate 或 release-preparation failure；allowlist、route 和实际 workflow names 必须由同一个 contract test 维护（projects/dockrev.md）。
• generic notifier checkout failed workflow 的 PR head 或 caller code，会把失败事件变成不可信代码执行边界；应只 checkout 默认分支的 trusted helper，并把失败 run 当作 metadata 输入（projects/dockrev.md）。
• 把组织级 reference 或历史实现当作项目默认 transport，会无证据引入外部 notifier、secret 或渠道。必须先通过 transport selection gate；未选定时阻断 rollout，选定配置缺失时显式失败。

• projects/blog-26.md
• projects/kaisoumail.md
• projects/flux-purr.md
• projects/dockrev.md
• topics/pr-label-release.md
• skills/policies/release-failure-notification/assets/templates/release-failure-notification-transport-gate.example.json
• skills/style-playbook/references/data/topics/release-failure-notification.json