# HLCC-PUSH-TO-DEPLOY-EVENT-PROTOCOL

状态：人工合并自动部署桥实现候选；服务器常驻部署Agent已在线，合并门待本提交部署与实测

普通推送本身不会产生部署事件。AI把代码和部署清单推入开发分支后，只有冰朔在光湖代码频道人工合并到 `main`，合并门才把该次合并实际改动的部署清单转换为 `guanghu.deployment-event/v1`。事件必须绑定：

- 代码频道仓库、分支和完整提交 SHA；
- `REQUEST-ID@完整提交SHA` 的不可变资源；
- `deployment/requests/` 下的部署清单。

Forgejo以HMAC-SHA256向 `/authz/api/deployment/forgejo-merge` 发送 `pull_request` 事件。合并门只接受 `action=closed`、`merged=true`、`merged_by=bingshuo`、目标仓库为 `bingshuo/guanghu-ice-heart` 且目标分支为 `main` 的事件；随后通过Forgejo只读API取得该PR改动文件。只有 `deployment/requests/<REQUEST-ID>.json` 被新增或修改时才写入队列。常驻部署 Agent 读取同一提交中的清单，执行备份、部署、健康检查与回滚。

人工合并本身就是本次部署批准，不再重复创建 `dispatch-approved-deployment` 工单。原 `/api/deployment/dispatch` 保留为没有代码频道合并界面时的兼容/灾备入口，不再作为正常发布流程。

没有部署清单的合并照常入库但不部署；普通push、关闭未合并、非登记合并者、错误签名、仓库/分支不匹配和无效事件均不会部署。服务器不扫描仓库猜测部署；同一Forgejo delivery与清单通过持久去重标记最多入队一次。

`resource` 中的 `REQUEST-ID` 必须与清单文件名完全一致：`deployment/requests/<REQUEST-ID>.json`。批准 A 而执行 B 必须在派发端和常驻 Agent 端分别拒绝。

首次新单元使用 `guanghu.architecture-provision-request/v1`；已经在线的 systemd 服务必须使用 `guanghu.existing-service-update-request/v1`，先完整备份声明目标，再重启和逐项验收，失败恢复全部旧文件与旧单元。二者不得互相冒充。

首次安装合并门时，由冰朔已授权且持有本机专用密钥的当前实例，按不可变候选提交、完整备份、健康检查和服务器私有回执完成一次性引导；不得为此绕回工单。引导完成后，正常发布只走“AI开发分支 → 合并请求 → 冰朔人工合并 → 自动部署与回执”。