CloudForge：一次真实主流程

成员向仓库推送一条分支时，平台必须同时守住仓库权限、Git 引用保护和后续任务的可恢复性。本指南沿这次推送解释代码托管的一条主路径，帮助维护者区分“对象已写入”和“后续处理已完成”。

下面的 case 是依据源码分支整理的代表性输入与结果，不是本轮线上观测。

输入或状态	动作与结果
有写权限的成员推普通分支	保护检查通过后转发；实际成功的引用登记事件
只读令牌推送	写入权限检查拒绝
部署令牌对未初始化仓库推送	拒绝引导默认分支
存储完成而后台中断	事件保留，恢复器可重试

Step 1: 请求先取得仓库权限

过渡运行时先从 D1 读取当前最低协议。状态缺失、无法读取或要求更高协议时，Git/LFS 在认证、读包与 Artifacts 调用前返回不缓存的 503；每次请求重新读取，公开仓库也不例外。该入口检查不能终止已经通过检查的在途推送，也不能约束尚未包含检查的历史 Worker。新角色仍保持关闭，完整发布边界见权限设计（仓库文件：docs/team-access-design.md#%E9%A6%96%E4%B8%AA%E8%BF%87%E6%B8%A1%E8%BF%90%E8%A1%8C%E6%97%B6%E7%9A%84%E5%AE%9E%E9%99%85%E8%BE%B9%E7%95%8C）。

成员通过 Git 客户端向仓库的 HTTPS 地址推送，令牌作为 Basic 密码。入口识别仓库和操作，按当前用户、令牌范围及仓库权限决定是否允许写入。公开仓库可以匿名读取，推送仍需凭据；只读令牌不会因为所属成员能写就获得写权限。

实例强制 MFA 约束浏览器会话；既有 PAT 和部署令牌使用仍遵循各自权限、期限与撤销规则，Git 客户端不进入网页验证码挑战。创建新令牌则需要当前策略合格的浏览器及近期验证。策略启用、旧浏览器重验、OAuth 撤销与最后管理员恢复见认证专题（仓库文件：docs/authentication.md#%E7%AE%A1%E7%90%86%E5%91%98%E8%AE%A4%E8%AF%81%E7%AD%96%E7%95%A5），不从 Git 令牌验证结果推断浏览器已完成 MFA。

对应实现（仓库文件：worker/src/git/http/handler.ts），定位 authenticateRepoRequest、handleGitRequest。

Step 2: 引用变动先经过保护

输入的包还不能直接送去存储。入口先解析 receive-pack 命令，保护默认分支、受保护分支和内部引用；不合格的更新返回 Git 的拒绝结果。部署令牌另有边界：仓库管理员必须先初始化默认分支，部署凭据不能借首次推送成为默认分支。

对应实现（仓库文件：worker/src/git/push-protection.ts），定位 decidePush；在入口中搜索 readReceiveRequest 与 deployToken。

Step 3: 存储回复决定哪些更新成立

允许的更新交给 Artifacts；服务器端的仓库凭据留在 Worker。回复支持状态报告时只采纳成功的引用，否则重新读取引用核对目标值。因此 HTTP 成功不能直接解释为每条引用都更新成功。

对应实现（仓库文件：worker/src/git/http/handler.ts），定位 successfulPushRefs、applied、recordPush。

Step 4: 先记事件，再返回推送结果

只要存在实际生效的引用，平台先把更新写入 D1 的推送事件，再安排后台后续工作并返回 Git 回复。这样响应后的执行被截断时仍有恢复依据。事件会触发配置刷新、检查、状态更新等工作，但这些工作的业务细节不在本指南范围内。

当原默认分支不存在时，后台会尝试从现有分支选择默认值。它只在 D1 中的默认值仍等于远端读取前的值时采用候选，保留管理员在等待期间保存的新选择；推送活动时间仍正常更新。同次后续工作使用写入返回的仓库设置，异步读取期间仓库已经删除则停止后续。Artifacts 与 D1 仍是独立操作，这个条件不保证远端引用在保存之后继续存在。

后续若排入 Actions，运行还会保留本次推送观察到的 before SHA；PR 运行另有自己的事件快照。命令可从 github.event 或 GITHUB_EVENT_PATH 读取支持的事件信息，旧运行缺失的历史字段保留未知。事件大小有上限，补充提交列表和文件列表可能缩减；具体支持范围见Actions 交接入口。

对应实现（仓库文件：worker/src/git/push-events.ts），定位 recordPush、afterPush、runPushEvent。

Step 5: 中断后按事件恢复

恢复按租约和尝试次数领取未完成事件，成功后标记完成；失败释放领取状态，留待下一次推送或定期恢复。后续处理需要允许重复执行，不能把一次后台调用当作唯一交付凭据。

对应实现（仓库文件：worker/src/__tests__/git/push-events.test.ts），定位 “后台被中断的事件”与“同一仓库的下一次推送”用例。

检查这条解释

yarn test:workers worker/src/__tests__/git/git-http.test.ts worker/src/__tests__/git/push-protection.test.ts worker/src/__tests__/git/push-events.test.ts

上述定向命令只验证 Git 主流程；全项目要求仍以根 AGENTS 和 docs/development.md 为准。各轮实际验证记录见指南变更记录；本地测试不表示真实推送或生产迁移已执行。

理解这条交接后，用代码地图定位下一次修改；需要反查依据时查看源码调查与边界证据。

证据状态：除特别标注外，本页基于当前源码已确认。