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。
- 如果尚未安装
ppioCLI,还需要 Node.js 20+ 和 npm。 - 最新版
ppioCLI(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。
- 经典 PAT:仓库级目标使用
- 要注册的准确仓库或组织 URL,例如
https://github.com/PPIO/github-actions-runner-controller。
部署到 PPIO(推荐)
1. 导出凭据 在当前 Shell 导出三个必填值,不要提交到仓库:GITHUB_CONFIG_URL 必须显式配置。脚本会拒绝 OWNER/REPO 和 OWNER/REPOSITORY 示例占位符,避免误部署到错误目标。
部署前确认 CLI 识别到目标 Team:
pause + auto-resume 的 Control Sandbox。这两个 Secret 是该可恢复沙箱的长期依赖,必须先 kill Control Sandbox,之后才能删除 Secret。
3. 把工作流指向 Runner
默认 Scale Set 标签为 ppio-scale-set。在目标仓库中,将需要在 PPIO 上运行的 Job 指向该标签:
.github/workflows/ci.yml
Prompt
多个仓库或组织
一个控制器只服务一个GITHUB_CONFIG_URL 目标。它覆盖多少仓库,取决于目标是个人仓库还是组织。
个人仓库。 注册到仓库 URL 的控制器只服务该仓库。若要在多个个人仓库中使用 PPIO Runner,为每个仓库各部署一次。脚本会根据规范化后的 GITHUB_CONFIG_URL 生成稳定的目标 ID,每个仓库都有独立的控制器标识、brokered Secret 和 Control Sandbox,第二次部署不会复用或覆盖第一次的。
恢复 Control Sandbox
恢复脚本既接受准确的沙箱 ID,也接受同一个 GitHub 目标 URL。按目标查找会同时检查 running 和 paused 状态的沙箱,发现多个匹配时直接报错,不会任意选择一个。备选:Local Docker
当控制器需要运行在你管理的机器上时使用 Local 模式。安装 Docker,并准备上面提到的同一个 GitHub PAT 和 PPIO API Key。 克隆仓库并复制示例环境文件。.env 已被 Git 忽略:
.env,填入目标 URL 和凭据。其余值与默认值一致,可以保持不变:
.env
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 内存,重编译任务建议调大:
.env 中设置,然后执行 docker compose up -d:
.env
SCALE_SET_NAME,再通过 runs-on 选择工具链。
配置
Hosted 部署还接受
CONTROLLER_TEMPLATE、GITHUB_SECRET_NAME、PPIO_SECRET_NAME 和 CONTROL_TIMEOUT。显式覆盖标识或 Secret 名称属于高级用法,常规的多项目部署使用按目标生成的默认值更安全。CONTROL_TIMEOUT 控制部署时以及 scripts/resume-hosted.sh 使用的生命周期。
生命周期归属与故障边界参阅项目的设计说明。