Skip to content

Bundle and verify a hermetic Git runtime for managed workspaces - #2199

Merged
zhiiw merged 6 commits into
apache:mainfrom
zhiiw:codex/bundled-git-runtime
Aug 5, 2026
Merged

Bundle and verify a hermetic Git runtime for managed workspaces#2199
zhiiw merged 6 commits into
apache:mainfrom
zhiiw:codex/bundled-git-runtime

Conversation

@zhiiw

@zhiiw zhiiw commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

What changed

  • provision a pinned Dugite Git distribution during release preparation and resolve it through a strict platform/architecture manifest;
  • fail closed when the manifest, archive provenance, Git version, entry executable, or runtime location does not match the admitted artifact;
  • bind managed-workspace artifacts to the admitted Git runtime identity and revalidate the executable before each Git invocation;
  • run managed Git operations with a hermetic environment and fixed policy that disables hooks, credentials, interactive authentication, SSH commands, remote protocols, config includes, alternates, and unsafe source configuration;
  • package the runtime and required notices on Windows and macOS, with release checks that require the bundled executable;
  • document the authority boundary, platform behavior, signing limitation, and follow-up trust-chain work.

Why

Managed workspaces cannot rely on an arbitrary system Git installation: PATH lookup, user/repository configuration, helper substitution, and runtime replacement would make the workspace authority depend on mutable host state. This change gives the workspace service one explicit Git artifact and one fail-closed execution profile.

The current manifest intentionally authenticates the entry executable and complete source-archive provenance, rather than hashing the helper tree before signing. On macOS, nested Mach-O signing changes helper bytes after preparation. A later publication slice will generate a final tree manifest after inner signing and bind that manifest into the outer application signature.

User and developer impact

  • packaged builds no longer need a separately installed system Git for managed-workspace lifecycle operations;
  • missing or modified bundled Git fails closed instead of falling back to PATH;
  • existing attached-workspace behavior and Desktop/CLI defaults are unchanged;
  • remote Git operations and submodules remain intentionally disabled in this version.

Validation

  • @maka/storage build
  • @maka/runtime-host build
  • bundled Git preparation tests: 3 passed
  • bundled Git runtime, native environment, workspace smoke, and workspace policy tests: 28 passed, 9 platform-gated Windows crash fixtures skipped
  • focused Windows packaging-order test: passed

One unrelated test newly present on main compares Windows paths against POSIX separators in windows-x64-release.test.mjs; it is outside this diff and was not folded into this PR.

中文说明

修改内容

  • 发布准备阶段从固定版本的 Dugite 包中生成 bundled Git,并通过严格的平台、架构 manifest 解析;
  • manifest、源归档 provenance、Git 版本、入口可执行文件或安装位置不匹配时 fail closed;
  • managed workspace artifact 绑定 Git runtime identity,每次 Git 调用前重新验证入口可执行文件;
  • 使用 hermetic 环境和固定执行策略,禁用 hooks、credential helper、交互认证、SSH command、远程协议、config include、object alternates 与不安全的 source config;
  • Windows/macOS 发布包纳入 Git runtime 与许可证通知,发布校验强制确认 bundled executable 存在;
  • 文档明确 authority 边界、平台行为、签名限制和后续 trust-chain 工作。

原因

Managed workspace 不能依赖任意系统 Git。PATH、用户/仓库配置、helper 替换和运行时文件变化,都会让 workspace authority 依赖可变的宿主机状态。本 PR 为 workspace service 提供唯一、显式、fail-closed 的 Git artifact 与执行 profile。

当前 manifest 有意验证入口 executable 和完整 source archive provenance,而没有在签名前固定 helper tree hash。macOS nested Mach-O 签名会在准备阶段之后改变 helper 字节;后续独立发布切片会在 inner signing 后生成最终 tree manifest,并由 outer application signature 保护该 manifest。

影响

  • 发布包执行 managed workspace 生命周期时不再要求用户单独安装系统 Git;
  • bundled Git 缺失或被修改时直接拒绝,不回退 PATH;
  • 不改变 attached workspace 与 Desktop/CLI 的默认行为;
  • 当前版本仍明确禁止 remote Git 与 submodule 操作。

验证

  • storage 与 runtime-host 构建通过;
  • bundled Git preparation 测试 3 项通过;
  • runtime、native environment、真实 workspace smoke 与 policy 测试 28 项通过,9 项 Windows crash fixture 按平台条件跳过;
  • Windows 打包顺序定向测试通过。

最新 main 另有一个 Windows release 测试使用 POSIX 分隔符断言 Windows 路径;它不在本 PR diff 中,因此没有混入本切片修复。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant