跳转到主要内容
PPIO Actions Runner Controller 让每个 GitHub Actions Job 都运行在独立的 PPIO Sandbox 中。一个长时运行的控制器从 GitHub 接收分配的 Job,为每个 Job 创建一个全新的 Runner 沙箱,Job 结束后立即销毁。每个 Job 都从干净的环境开始,无需维护任何 Runner 机器。 控制器使用 GitHub 官方的 actions/scaleset 客户端接收 Job 和 Runner 容量需求。同一个控制器镜像可以运行在两个位置:PPIO Hosted 模式(推荐)把控制器放在 PPIO 上一个长时运行的 Control Sandbox 中,不依赖你的本机保持在线;Local Docker 模式把控制器运行在你管理的机器上,Runner 沙箱仍然创建在 PPIO 上。
控制器使用 GitHub 的 Scale Set API,GitHub 目前将其标记为 Public Preview。客户端 API 已稳定,但其 Go 接口仍可能变化。

工作原理

Hosted 模式直接使用两个 PPIO 公共 Template,部署前无需构建任何镜像: 每个 Job 的 JIT(just-in-time)Runner 配置通过 adapter 的 stdin 和沙箱文件系统 API 送达 Runner 沙箱。Runner 入口脚本读取后立即删除该文件,并且只导出给 Runner 子进程。该配置不会出现在沙箱创建时的环境变量、元数据、进程参数或控制器日志中。

前置条件

在执行部署脚本的机器上准备:
  • Bash 和 Python 3。
  • 如果尚未安装 ppio CLI,还需要 Node.js 20+ 和 npm。
  • 最新版 ppio CLI(2.1.0 或更高)。参阅 CLI 认证。
  • 一个 PPIO API Key,在 PPIO 控制台获取。它决定持有 Control Sandbox 和 brokered Secret 的 PPIO Team,不需要额外的浏览器登录。该 Key 所属的 Team 必须位于 cn-beijing-1 区域(cn-beijing-1.sandbox.ppio.com),因为 brokered Secret 仅在该区域可用。
  • 一个有权管理自托管 Runner 的 GitHub personal access token(PAT):
    • 经典 PAT:仓库级目标使用 repo,组织级目标使用 admin:org。
    • 细粒度 PAT:仓库级目标授予 Administration: read and write;组织级目标同时授予 Administration: read 和 Self-hosted runners: read and write。
  • 要注册的准确仓库或组织 URL,例如 https://github.com/PPIO/github-actions-runner-controller。
如未安装 CLI:

部署到 PPIO(推荐)

控制器运行在一个长时运行的 Control Sandbox 中,会常驻并持续计费。不使用时请用 ppio sandbox kill 关闭该沙箱,否则会一直产生费用。沙箱 ID 在部署脚本输出的 JSON 中。
1. 导出凭据 在当前 Shell 导出三个必填值,不要提交到仓库:
GITHUB_CONFIG_URL 必须显式配置。脚本会拒绝 OWNER/REPO 和 OWNER/REPOSITORY 示例占位符,避免误部署到错误目标。 部署前确认 CLI 识别到目标 Team:
2. 运行部署脚本 克隆仓库,在仓库根目录运行 Hosted 部署:
脚本运行在本机,并在 PPIO 中创建长时运行的 Control Sandbox。成功后会打印目标标识、Control Sandbox ID 和健康状态:
请保留这段输出,下面的恢复脚本可以直接使用其中的沙箱 ID。 部署脚本会创建或更新两个 brokered Secret,并创建一个 60 年超时、pause + auto-resume 的 Control Sandbox。这两个 Secret 是该可恢复沙箱的长期依赖,必须先 kill Control Sandbox,之后才能删除 Secret。 3. 把工作流指向 Runner 默认 Scale Set 标签为 ppio-scale-set。在目标仓库中,将需要在 PPIO 上运行的 Job 指向该标签:
.github/workflows/ci.yml
如果你使用 coding agent,也可以让它帮你编写工作流:
Prompt
控制器会创建或复用同名的 Scale Set,并且在关闭时故意不删除它,因此控制器可以安全重启。

多个仓库或组织

一个控制器只服务一个 GITHUB_CONFIG_URL 目标。它覆盖多少仓库,取决于目标是个人仓库还是组织。 个人仓库。 注册到仓库 URL 的控制器只服务该仓库。若要在多个个人仓库中使用 PPIO Runner,为每个仓库各部署一次。脚本会根据规范化后的 GITHUB_CONFIG_URL 生成稳定的目标 ID,每个仓库都有独立的控制器标识、brokered Secret 和 Control Sandbox,第二次部署不会复用或覆盖第一次的。
组织。 注册到组织 URL 的控制器服务该组织下的所有仓库。使用组织 URL 和前置条件中组织级目标的 PAT 权限部署一次即可:
若组织中的公开仓库也要使用这些 Runner,在 GitHub 上打开组织的 Settings → Actions → Runner groups → Default,启用 Allow public repositories。

恢复 Control Sandbox

恢复脚本既接受准确的沙箱 ID,也接受同一个 GitHub 目标 URL。按目标查找会同时检查 running 和 paused 状态的沙箱,发现多个匹配时直接报错,不会任意选择一个。
手工恢复后必须紧接着执行 ppio sandbox set-timeout。ppio sandbox resume 不接受超时参数,PPIO 会把恢复后的沙箱重置为较短的默认生命周期(约五分钟)。生命周期仍是 pause + auto-resume,但不重设超时的话控制器几乎会立刻再次暂停。
早于目标元数据功能创建的 Control Sandbox 仍需使用沙箱 ID 恢复。

备选:Local Docker

当控制器需要运行在你管理的机器上时使用 Local 模式。安装 Docker,并准备上面提到的同一个 GitHub PAT 和 PPIO API Key。 克隆仓库并复制示例环境文件。.env 已被 Git 忽略:
编辑 .env,填入目标 URL 和凭据。其余值与默认值一致,可以保持不变:
.env
启动控制器并检查健康端点:
Local 模式拉取固定版本的 ppinfra/github-actions-controller:v0.1.2 镜像。凭据只通过 .env 中的 GITHUB_TOKEN 和 PPIO_API_KEY 提供。工作流仍使用上面的 runs-on: ppio-scale-set。控制器接受的全部变量见配置。

自定义 Runner Template

需要预装工具时,在公共 Runner 镜像之上构建自己的 Template,再让控制器使用它。ppio template create 的完整说明见构建 Template。 1. 编写 Template Dockerfile 以控制器仓库中的 templates/runner/ppio.Dockerfile 为起点。保留控制器依赖的三个约定:user 用户、/home/user/actions-runner 目录和 entrypoint.sh 启动命令。控制器会把每个 Job 的 JIT 配置写入该目录,由入口脚本读取。
templates/runner/ppio.Dockerfile
按需追加 apt-get install 包或下载其他工具。rustup、nvm 这类用户级工具请在 USER user 之后安装,使其落在 /home/user 下。 2. 构建 Template 名字不要与公共的 github-actions-runner 冲突。默认规格为 2 vCPU、4 GB 内存,重编译任务建议调大:
每次修改 Dockerfile 后用相同名字重新构建;如果平台拒绝重名,换一个新名字。 3. 设置 PPIO_RUNNER_TEMPLATE Hosted 模式在部署时读取 Template 名。先 kill 该目标现有的 Control Sandbox,再带上覆盖值重新部署:
Local Docker 模式在 .env 中设置,然后执行 docker compose up -d:
.env
工作流无需修改,重新运行 Job 即可落到新 Template 上。 一个控制器只使用一个 Runner Template。需要多套工具链时,为每个 Template 部署一个控制器,使用不同的 SCALE_SET_NAME,再通过 runs-on 选择工具链。

配置

Hosted 部署还接受 CONTROLLER_TEMPLATE、GITHUB_SECRET_NAME、PPIO_SECRET_NAME 和 CONTROL_TIMEOUT。显式覆盖标识或 Secret 名称属于高级用法,常规的多项目部署使用按目标生成的默认值更安全。CONTROL_TIMEOUT 控制部署时以及 scripts/resume-hosted.sh 使用的生命周期。 生命周期归属与故障边界参阅项目的设计说明。
最后修改于 2026年11月16日