Preloop 发布本地自托管 GitHub Actions 引擎，微虚拟机中运行工作流

失败的步骤、在另一个窗格中修复、然后重新运行，全部在本地完成，无需推送。

preloop 是本地自托管的 GitHub Actions 等价物。引擎（preloop serve）像 GitHub 一样接受工作流：${{ }} 表达式、矩阵构建、可复用工作流、并发组、OIDC 等。它在硬件隔离的 microvm 上执行这些工作流，支持 Windows/MacOS 或 Linux，并能在 300ms 内恢复。你的 .github/workflows 无需修改即可运行，而且你可以针对未提交的更改运行 CI（会遵循 .gitignored/untracked 规则）。

它使用官方 actions/runner 协议，因此你可以使用官方 runner 来注册、轮询、执行并向其报告，而无需消耗 GitHub 托管的分钟数。你也可以使用我们的 Rust 等价 runner——安装体积小 36 倍，峰值内存低 19 倍（见下方基准测试）。

Preloop 不仅仅依赖 GitHub Webhooks 来更新 CI 状态。我们运行一个 Webhook 看门狗来检测漂移，并根据 GitHub API 将你的提交与收到的 webhook 进行对账。你可以在本地运行已提交的更改并运行工作流，并传递 --push 或 --create-pr 来打开一个 PR，同时正确更新检查状态（新 PR 默认以草稿形式打开，见 --pr-draft）。这在 GitHub 的 webhook 服务宕机时可能很有用。

快速开始

# Install (macOS/Linux), any one of:
brew install preloopdev/tap/preloop   # Homebrew — formula published by the release workflow
npm install -g @preloop-dev/cli       # npm — same release binaries, fetched at install time

# Or fetch the installer at a release tag, read it, then run it. It downloads
# the release binaries and verifies every artifact's sha256.
ver=v0.33.6   # any tag from https://github.com/preloopdev/preloop/releases
curl -fsSL "https://raw.githubusercontent.com/preloopdev/preloop/$ver/install.sh" -o install.sh
less install.sh
sh install.sh

preloop init              # wizard: credentials, golden image, how to run
preloop serve            # engine on 127.0.0.1:9090

cd my-repo
preloop run -f .github/workflows/ci.yml --event pull_request

preloop init 会引导完成四个步骤（GitHub 凭据、每个作业 fork 自的黄金镜像、运行模式、预检），并将结果写入 ~/.preloop/config.toml。在没有终端的情况下，它接受与标志相同的答案——preloop init --probe --json 会报告此主机支持的功能而不做任何更改，preloop init --help 记录了每个标志。它是通往 preloop setup github 和精心挑选的 PRELOOP_RUNNER_BASE_IMAGE 曾经功能的一键式入口。 这会在前台启动服务器，但你也可以将其分离（添加 -d）。首次运行可能需要几分钟，因为我们需要下载 SBOM 认证的官方 GitHub Runner OCI 镜像的打包 vm 制品（runner-image-blobs）并在本地创建一个“黄金”vm。这个黄金 vm 将按作业在 300 毫秒内 fork。官方 GitHub 镜像压缩后约 9GB，解压后接近 50 GB，因此建议至少 80GB 磁盘空间。你也可以从 OCI 镜像定义自己的黄金 vm——preloop init 会为你记录。更多详细信息请参阅 docs/vm-images.md。每个 vm 的内存是弹性的，因此只消耗作业中实际使用的内存。控制平面空闲 rss 约为 25MB。 不想运行脚本：从 最新发布 获取 preloop-cli-<target>.tar.gz 及其 .sha256，验证校验和，将 preloop 放到你的 PATH 上，然后运行 preloop update 安装固定版本的 SmolVM 运行时。每个发布资产还带有无密钥构建来源证明（gh attestation verify <asset> --repo preloopdev/preloop）。 MicroVM 作业需要位于 <prefix>/lib/preloop/runner/<triple>/preloop-runner 的 Linux 客户机 runner；install.sh 会放置它，docs/self-hosting.md §3 中有手动命令。

在 Apple Silicon 上，x86_64 黄金镜像也通过 Rosetta 2 转换运行（对每个 VM 自动启用）。性能比 arm64 原生略慢，因此在 Apple Silicon 上尽可能优先使用 arm64 黄金镜像。此路径尚不支持 Docker actions：VM 的 Docker 内的 amd64 镜像缺少 Rosetta 挂载，因此会失败并出现一个晦涩的 rosetta-wrapper 错误。即将修复。

你可以在本地模拟大多数甚至所有 GitHub 事件。对于某些事件，你可能需要添加一个 payload。 有关可以传递的更多标志，请参阅 docs/cli_reference.md。

要继续设置，请参阅 GitHub App 和 PAT 凭据、密钥、配置文件以及故障排除指南：docs/setup.md

将其作为服务器运行、服务安装、每个运行时参数，以及如何暴露它（仅 tailnet、Tailscale Funnel、Cloudflare Tunnel 或你自己的域名）：docs/self-hosting.md

仅运行器

preloop-runner 是 actions/runner 的即插即用 Rust 替代品——它以相同方式向 GitHub（或 preloop 服务器）注册，安装体积小 36 倍，峰值内存低 19 倍：

curl -fsSL https://raw.githubusercontent.com/preloopdev/preloop/main/install.sh | sh -s -- --runner
export PATH="$HOME/.local/bin:$PATH"
preloop-runner configure --url https://github.com/owner/repo --token <registration-token>
preloop-runner run

每个版本还会发布适用于 Linux（x86_64/aarch64）、macOS（x86_64/arm64）和 Windows（x86_64）的独立二进制文件，每个都附带 CycloneDX SBOM（preloop-runner_<triple>.cdx.json）和 sha256 校验和：

curl -fsSLO https://github.com/preloopdev/preloop/releases/latest/download/preloop-runner-<triple>
chmod +x preloop-runner-<triple>
./preloop-runner-<triple> configure --url https://github.com/owner/repo --token <registration-token>
./preloop-runner-<triple> run

或者使用带持久卷的容器镜像：

docker run --rm -v preloop-runner-data:/runner \
  ghcr.io/preloopdev/preloop-runner:latest \
  --runner-root /runner configure --url … --token … --unattended
docker run --rm -v preloop-runner-data:/runner \
  ghcr.io/preloopdev/preloop-runner:latest \
  --runner-root /runner run

详情：docs/setup.md。

它与其他方案有何不同。

• 我们使用真实的运行器协议，而非行为近似：官方运行器二进制文件可原样对其工作。
• 为每个作业提供硬件隔离的 microvm，可在 300ms 内启动，弹性扩缩容，且跨平台。
• 支持 GitHub App 和细粒度 PAT，并可按作业铸造令牌，以便你的检查得到更新。
• 由 DAP 驱动的作业检查：在入口处附加，检查实时 GitHub/作业上下文，暂停并继续，并支持步骤级重试。
• 经过大量测试，包括属性测试、差分测试和形式化验证。一致性是基本要求。
• 面向代理和开发者工具的 NDJSON 事件输出。

如需更详细的对比，请参阅：docs/preloop_vs_others.md

代理驱动的调试

当提交的运行启用了 DAP 调试器时，preloop 会将作业保持在入口处，直到调试器附加。代理或兼容的 DAP 客户端随后可以检查实时的 github、env、runner、job、steps 和 secrets 作用域，然后再继续作业。当工作流 YAML 看起来正确，但运行时事件负载、矩阵值或生成的上下文有误时，这非常有用。

preloop dap <run-id>

基准测试

preloop-runner 是从零开始用 Rust 重新实现的 actions/runner，使用相同的协议——官方运行器可原样对 preloop 工作，preloop-runner 也以相同方式向 GitHub 注册。相同的服务器、相同的作业，在同一台机器上测量（M1 Pro，macOS，3 次的中位数）：

官方 tarball 将 node20 + node24（约 350 MB）打包进每次安装；preloop-runner 以单个二进制文件形式发布，并将一份共享的只读外部依赖副本挂载到每个 VM 中（或将其烘焙进黄金镜像）。10 个空闲运行器的预热池成本约为 90 MB，而非约 670 MB。

复现：scripts/bench-runner-compare.sh（设置 BENCH_RUNS=N；需要 target/release/preloop-runner 和 ~/.cache/actions-runner/current 中的官方运行器）。交互式图表：benchmarks/runner-compare.html。

关于去哪里查找信息的文档。

许可证

一个项目，两种许可证：

• 除控制平面外的一切均采用 MIT 许可证——包括 CLI、Rust runner、parser/expression/protocol crates、VM 编排器以及文档。
• 控制平面（preloop serve / preloop-runner-server）采用 FSL-1.1-MIT，因此是源码可得的。你可以出于任何非竞争性目的使用、修改和再分发它（内部 CI、商业产品、fork），并且它会在每个版本发布两周年之际转换为 MIT。所谓“非竞争性”是指：你不能将其作为与 preloop 自身产品相竞争的托管 CI 服务来提供。

完整条款：crates/preloop-runner-server/LICENSE（FSL-1.1-MIT），其余部分采用 MIT。

致谢

如果没有以下项目，这个项目尤其不可能实现：

• smolvm——每个作业都在其中执行的 microVM 运行时
• runner.server——本项目所基于的协议逆向工程