# 仓库、分支与 wishforge.yaml 约定 ## 仓库与传输 - 仓库地址只支持不带内嵌凭据、查询串与片段的 HTTPS。SSH 与 SCP 形式的地址在创建项目和启动执行器之前就被拒绝。开发模式下设置 `WF_GIT_ALLOW_LOCAL_HTTP=true` 后允许本机回环地址的 HTTP;生产模式拒绝。 - Git 命令不读取全局与系统配置、不跟随 HTTP 重定向、不使用宿主机的凭据缓存。仓库范围的短期凭据通过进程环境中的请求头传入,不出现在 URL 中,只发给持有执行租约的身份:executor 只读,verifier 可写。 - 不支持 Git LFS、子模块与 SSH agent。 ## 基线与检查点 - 新运行克隆仓库后,以 `refs/remotes/origin/` 指向的 commit 为基线;愿望指定了起点分支(`sourceBranch`)时改用 `refs/remotes/origin/`。远端默认 HEAD 与同名标签不会被选中。目标分支不存在时明确报错(`TARGET_BRANCH_UNAVAILABLE`);起点分支不存在时运行进入 `git_storage` 等待(`SOURCE_BRANCH_UNAVAILABLE`),推送该分支后继续即可。起点分支不能是目标分支,也不能是平台自己的 `wishforge/` 分支。分支名与引用表达式在创建项目与运行时都会校验。 - 检查点是相对基线的增量 Git bundle(`..HEAD`)加上二进制补丁及其摘要。bundle 与补丁各不超过 4 MiB;配置了对象存储时 bundle 存入对象存储(见 [artifact-storage.md](artifact-storage.md))。工作区没有变化时检查点不含 bundle。 - 恢复检查点时,从项目仓库克隆基线 commit,再应用 bundle 并核对补丁摘要;恢复出的 commit 与检查点不一致时拒绝。基线已不在仓库中(例如目标分支被强制推送)时报 `CHECKPOINT_BASE_UNAVAILABLE`,运行进入等待。 - 执行器安装依赖后,安装产生的未跟踪文件(如 `node_modules/`)写入 `.git/info/exclude`,不会进入检查点。 ## 合入 - 项目划出后端代码(`codeReview.paths`,glob;`exceptPaths` 为放行的前端与其他路径)时,验证通过后、合入前,改到后端代码(或运行从其他分支开始)、而提交人或补充过需求的人不能直接合入(许愿范围不是 `full`)的运行进入 `code_review` 等待,由有「审核代码」权限的人批准后才合入;批准绑定被审核的 commit 与需求版本。声明只改前端(`frontendOnly`)的愿望改到后端代码时不运行检查,失败类型为 `scope`:修复轮开始前平台把这些文件恢复到运行开始时的内容,Agent 只改前端重做。改动路径不做重命名识别,挪动的文件在新旧两个位置都算改到。 - 撤销运行(`revertOf`)在目标分支最新代码上三方反向应用被撤销运行合入前后两个 commit 之间的改动,之后的提交保留;冲突时由执行器解决,之后照常验证与合入。 - verifier 在独立的裸仓库(远端的缓存)中准备候选 commit:目标分支没有移动时直接使用已验证的 commit;否则把它合并到目标分支的最新提交上,并对合并结果重新验证。 - 推送使用 `--force-with-lease` 并先做祖先检查;推送时目标分支又前进了,就基于新的提交重新准备候选,最多三次。 - 合并结果未通过检查、而不带本次改动的目标分支同样未通过(运行的起点能通过)时,运行进入 `target_broken` 等待,由人修好目标分支后继续,不消耗修复轮数;其余情况按一轮修复处理。 - 合并冲突时提交失败的集成证据(冲突文件与目标 commit),按一轮修复处理:修复轮先把最新目标分支合并进工作区,执行器解决冲突标记,检查点以该目标 commit 为基线。修复轮数用尽时运行进入 `integration_conflict` 等待。 - IDE 工作区(FR-H2):有编辑会话时得到 15 分钟的仓库令牌,令牌里写明只能更新 `refs/heads/ide/`。平台 Git 对每次推送运行 pre-receive 钩子,越界的引用被拒绝;平台自己的合入不受这个限制。所有推送都只接受快进,也不能删除分支。IDE 分支经由从它开始的愿望进入目标分支,过程与 Agent 的改动相同。 - 平台 Git 的管理接口 `POST /refs`(`{tenantId, projectId, prefix}`)按最近提交时间列出某个前缀下的分支,工作台据此列出 IDE 分支。 - GitHub 仓库走评审路径:只推送不可变的 `wishforge/<运行>/` 分支,控制面创建或对账对应的 PR 并等待合并(`github_review`);合并后在 GitHub 实际产生的合并 commit 上重新验证,再提交集成证据。未配置 GitHub App 的 GitHub 仓库不会退回直接推送(`github_unconfigured`)。安装令牌按仓库授权而不是按分支授权,目标分支仍需要分支保护。 ## wishforge.yaml V1 仓库根目录可以提交 `wishforge.yaml`(示例:[examples/wishforge.yaml](../../examples/wishforge.yaml))。它是可选的;没有它时只使用项目设置。 | 字段 | 作用 | |---|---| | `dev.install` | 依赖安装命令(参数数组)。只在项目没有配置受保护的安装命令时使用,执行器开始前与验证前各运行一次,在 `dev.workingDirectory` 中执行 | | `dev.runtime`、`dev.command` | 开发提示;平台不执行 `dev.command` | | `tests` | 补充测试,追加在受保护的验证命令与验收配置之后,不能替代它们 | | `build` | Dockerfile 与构建上下文,必须与项目交付配置一致 | | `ports`、`health` | 端口与健康检查,必须与项目交付配置一致 | | `resources` | 资源请求,不能超过 provisioner 给出的上限 | | `migrations` | 声明需要数据迁移时提高发布风险;迁移命令不会被自动执行 | 读取规则:只读取已提交的根目录 `wishforge.yaml`,并核对工作区 HEAD、Git 树条目与文件内容一致;文件必须是不超过 64 KiB 的普通 UTF-8 文件。符号链接、目录、YAML 别名、自定义标签、重复键、多文档、路径穿越与工作区漂移都会被拒绝;未知字段(包括试图授予环境、凭据、权限或审批豁免的字段)同样被拒绝。声明 `migrations.required: false` 不能证明变更不含迁移,发布风险仍由验证器的变更分类决定。