> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions Runner

> 查阅 GitHub Actions Runner Controller 接入 PPIO Agent 沙箱的说明，了解托管部署、Local Docker 与自定义 Runner Template 的配置方式，为在隔离沙箱中运行 CI 任务提供参考。

[PPIO Actions Runner Controller](https://github.com/PPIO/github-actions-runner-controller) 让每个 GitHub Actions Job 都运行在独立的 PPIO Sandbox 中。一个长时运行的控制器从 GitHub 接收分配的 Job，为每个 Job 创建一个全新的 Runner 沙箱，Job 结束后立即销毁。每个 Job 都从干净的环境开始，无需维护任何 Runner 机器。

控制器使用 GitHub 官方的 [`actions/scaleset`](https://github.com/actions/scaleset) 客户端接收 Job 和 Runner 容量需求。同一个控制器镜像可以运行在两个位置：PPIO Hosted 模式（推荐）把控制器放在 PPIO 上一个长时运行的 Control Sandbox 中，不依赖你的本机保持在线；Local Docker 模式把控制器运行在你管理的机器上，Runner 沙箱仍然创建在 PPIO 上。

> [!NOTE]
>
> 控制器使用 GitHub 的 Scale Set API，GitHub 目前将其标记为 Public Preview。客户端 API 已稳定，但其 Go 接口仍可能变化。

## 工作原理

```mermaid theme={null}
flowchart LR
    G["GitHub Actions<br/>分配 Job 和 JIT 配置"] --> C["Control Sandbox<br/>github-actions-controller"]
    C --> T["Runner Template<br/>github-actions-runner"]
    T --> R["临时 Runner Sandbox<br/>每个 Job 一个"]
    R --> K["Job 完成<br/>kill Sandbox"]
```

Hosted 模式直接使用两个 PPIO 公共 Template，部署前无需构建任何镜像：

| 用途 | 公共 Template |
| - | - |
| Control Sandbox | `github-actions-controller` |
| 临时 CI Runner | `github-actions-runner` |

每个 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 认证](https://ppio.com/docs/sandbox/cli-auth.md)。
* 一个 PPIO API Key，在 [PPIO 控制台](https://ppio.com/settings/key-management)获取。它决定持有 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：

```bash theme={"system"} theme={null}
npm install --global ppio-sandbox-cli@latest
ppio --version
```

***

## 部署到 PPIO（推荐）

> [!WARNING]
>
> 控制器运行在一个[长时运行](https://ppio.com/docs/sandbox/sandbox-long-running.md)的 Control Sandbox 中，会常驻并持续计费。不使用时请用 `ppio sandbox kill` 关闭该沙箱，否则会一直产生费用。沙箱 ID 在部署脚本输出的 JSON 中。

**1. 导出凭据**

在当前 Shell 导出三个必填值，不要提交到仓库：

```bash theme={"system"} theme={null}
export GITHUB_CONFIG_URL=https://github.com/OWNER/REPOSITORY
export GITHUB_TOKEN=YOUR_GITHUB_PAT
export PPIO_API_KEY=YOUR_PPIO_API_KEY
```

`GITHUB_CONFIG_URL` 必须显式配置。脚本会拒绝 `OWNER/REPO` 和 `OWNER/REPOSITORY` 示例占位符，避免误部署到错误目标。

部署前确认 CLI 识别到目标 Team：

```bash theme={"system"} theme={null}
ppio auth info
```

**2. 运行部署脚本**

克隆仓库，在仓库根目录运行 Hosted 部署：

```bash theme={"system"} theme={null}
git clone https://github.com/PPIO/github-actions-runner-controller.git
cd github-actions-runner-controller
bash scripts/deploy-hosted.sh
```

脚本运行在本机，并在 PPIO 中创建长时运行的 Control Sandbox。成功后会打印目标标识、Control Sandbox ID 和健康状态：

```json theme={"system"} theme={null}
{"targetId":"ppio-github-actions-runn-712433e3dc","controllerId":"ppio-hosted-ppio-github-actions-runn-712433e3dc","sandboxId":"...","healthy":true}
```

请保留这段输出，下面的恢复脚本可以直接使用其中的沙箱 ID。

部署脚本会创建或更新两个 brokered Secret，并创建一个 60 年超时、`pause + auto-resume` 的 Control Sandbox。这两个 Secret 是该可恢复沙箱的长期依赖，必须先 kill Control Sandbox，之后才能删除 Secret。

**3. 把工作流指向 Runner**

默认 Scale Set 标签为 `ppio-scale-set`。在目标仓库中，将需要在 PPIO 上运行的 Job 指向该标签：

```yaml .github/workflows/ci.yml theme={"system"} theme={null}
jobs:
  test:
    runs-on: ppio-scale-set
```

如果你使用 coding agent，也可以让它帮你编写工作流：

```text Prompt theme={"system"} theme={null}
为我的仓库编写一个运行在 ppio-scale-set 上的 GitHub Actions 工作流 YAML。
参考：https://github.com/PPIO/github-actions-runner-controller/blob/main/README.md
```

控制器会创建或复用同名的 Scale Set，并且在关闭时故意不删除它，因此控制器可以安全重启。

### 多个仓库或组织

一个控制器只服务一个 `GITHUB_CONFIG_URL` 目标。它覆盖多少仓库，取决于目标是个人仓库还是组织。

**个人仓库。** 注册到仓库 URL 的控制器只服务该仓库。若要在多个个人仓库中使用 PPIO Runner，为每个仓库各部署一次。脚本会根据规范化后的 `GITHUB_CONFIG_URL` 生成稳定的目标 ID，每个仓库都有独立的控制器标识、brokered Secret 和 Control Sandbox，第二次部署不会复用或覆盖第一次的。

```bash theme={"system"} theme={null}
GITHUB_CONFIG_URL=https://github.com/OWNER/ANOTHER_REPOSITORY \
  bash scripts/deploy-hosted.sh
```

**组织。** 注册到组织 URL 的控制器服务该组织下的所有仓库。使用组织 URL 和[前置条件](#前置条件)中组织级目标的 PAT 权限部署一次即可：

```bash theme={"system"} theme={null}
GITHUB_CONFIG_URL=https://github.com/ORG_NAME \
  bash scripts/deploy-hosted.sh
```

若组织中的公开仓库也要使用这些 Runner，在 GitHub 上打开组织的 **Settings → Actions → Runner groups → Default**，启用 **Allow public repositories**。

### 恢复 Control Sandbox

恢复脚本既接受准确的沙箱 ID，也接受同一个 GitHub 目标 URL。按目标查找会同时检查 running 和 paused 状态的沙箱，发现多个匹配时直接报错，不会任意选择一个。

```bash theme={"system"} theme={null}
scripts/resume-hosted.sh SANDBOX_ID

# 或按目标 URL 查找沙箱：
GITHUB_CONFIG_URL=https://github.com/OWNER/REPOSITORY \
  scripts/resume-hosted.sh

# 等价的核心命令：
ppio sandbox resume SANDBOX_ID
ppio sandbox set-timeout SANDBOX_ID 525600h
```

> [!WARNING]
>
> 手工恢复后必须紧接着执行 `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 忽略：

```bash theme={"system"} theme={null}
git clone https://github.com/PPIO/github-actions-runner-controller.git
cd github-actions-runner-controller
cp .env.example .env
```

编辑 `.env`，填入目标 URL 和凭据。其余值与默认值一致，可以保持不变：

```bash .env theme={"system"} theme={null}
GITHUB_CONFIG_URL=https://github.com/OWNER/REPOSITORY
GITHUB_TOKEN=YOUR_GITHUB_PAT
PPIO_API_KEY=YOUR_PPIO_API_KEY
PPIO_DOMAIN=cn-beijing-1.sandbox.ppio.com
PPIO_RUNNER_TEMPLATE=github-actions-runner
SCALE_SET_NAME=ppio-scale-set
RUNNER_LABELS=ppio-scale-set
MIN_RUNNERS=0
MAX_RUNNERS=10
RUNNER_TIMEOUT=1h
RECONCILE_INTERVAL=30s
ORPHAN_GRACE=15m
```

启动控制器并检查健康端点：

```bash theme={"system"} theme={null}
docker compose up -d
curl http://127.0.0.1:8080/healthz
```

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](https://ppio.com/docs/sandbox/sandbox-template.md)。

**1. 编写 Template Dockerfile**

以控制器仓库中的 `templates/runner/ppio.Dockerfile` 为起点。保留控制器依赖的三个约定：`user` 用户、`/home/user/actions-runner` 目录和 `entrypoint.sh` 启动命令。控制器会把每个 Job 的 JIT 配置写入该目录，由入口脚本读取。

```dockerfile templates/runner/ppio.Dockerfile theme={"system"} theme={null}
FROM ppinfra/github-actions-runner:v0.1.2
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
      build-essential pkg-config libssl-dev zstd \
    && rm -rf /var/lib/apt/lists/*
USER user
CMD ["/home/user/actions-runner/entrypoint.sh"]
```

按需追加 `apt-get install` 包或下载其他工具。rustup、nvm 这类用户级工具请在 `USER user` 之后安装，使其落在 `/home/user` 下。

**2. 构建 Template**

名字不要与公共的 `github-actions-runner` 冲突。默认规格为 2 vCPU、4 GB 内存，重编译任务建议调大：

```bash theme={"system"} theme={null}
ppio template create my-gcc-runner \
  --path templates/runner \
  --dockerfile ppio.Dockerfile \
  --cpu-count 4 --memory-mb 8192 \
  --cmd /home/user/actions-runner/entrypoint.sh \
  --ready-cmd 'test -x /home/user/actions-runner/entrypoint.sh'
```

每次修改 Dockerfile 后用相同名字重新构建；如果平台拒绝重名，换一个新名字。

**3. 设置 PPIO\_RUNNER\_TEMPLATE**

Hosted 模式在部署时读取 Template 名。先 kill 该目标现有的 Control Sandbox，再带上覆盖值重新部署：

```bash theme={"system"} theme={null}
ppio sandbox kill CONTROL_SANDBOX_ID
PPIO_RUNNER_TEMPLATE=my-gcc-runner bash scripts/deploy-hosted.sh
```

Local Docker 模式在 `.env` 中设置，然后执行 `docker compose up -d`：

```bash .env theme={"system"} theme={null}
PPIO_RUNNER_TEMPLATE=my-gcc-runner
```

工作流无需修改，重新运行 Job 即可落到新 Template 上。

一个控制器只使用一个 Runner Template。需要多套工具链时，为每个 Template 部署一个控制器，使用不同的 `SCALE_SET_NAME`，再通过 `runs-on` 选择工具链。

***

## 配置

| 变量 | 默认值 | 说明 |
| - | - | - |
| `GITHUB_CONFIG_URL` | 必填 | 仓库或组织 URL |
| `GITHUB_TOKEN` | 必填 | GitHub PAT |
| `PPIO_API_KEY` | 必填 | PPIO Team API Key |
| `PPIO_DOMAIN` | Hosted 模式为 `cn-beijing-1.sandbox.ppio.com` | PPIO Sandbox 区域域名；brokered Secret 需要该区域 |
| `PPIO_RUNNER_TEMPLATE` | 必填 | Runner Template 名称或 ID，见[自定义 Runner Template](#自定义-runner-template) |
| `SCALE_SET_NAME` | `ppio`（部署脚本与 `.env.example` 使用 `ppio-scale-set`） | Scale Set 名称 |
| `RUNNER_LABELS` | Scale Set 名称 | 逗号分隔的 Runner 标签 |
| `RUNNER_GROUP` | `default` | GitHub Runner 组 |
| `MIN_RUNNERS` / `MAX_RUNNERS` | `0` / `10` | 容量上下限 |
| `RUNNER_TIMEOUT` | `1h` | 每个 Job 沙箱的硬性生命周期 |
| `RECONCILE_INTERVAL` | `30s` | 周期性收敛间隔 |
| `ORPHAN_GRACE` | `15m` | 已暂停孤儿沙箱的保留时间 |
| `CONTROLLER_ID` | Hosted 模式下由目标 URL 派生 | 所有权标识 |
| `METRICS_ADDR` | `:8080` | 健康检查与指标监听地址 |
| `PYTHON` | `python3` | adapter 使用的 Python 可执行文件 |
| `PPIO_ADAPTER` | `/app/provisioner/ppio/adapter.py` | adapter 路径 |

Hosted 部署还接受 `CONTROLLER_TEMPLATE`、`GITHUB_SECRET_NAME`、`PPIO_SECRET_NAME` 和 `CONTROL_TIMEOUT`。显式覆盖标识或 Secret 名称属于高级用法，常规的多项目部署使用按目标生成的默认值更安全。`CONTROL_TIMEOUT` 控制部署时以及 `scripts/resume-hosted.sh` 使用的生命周期。

生命周期归属与故障边界参阅项目的[设计说明](https://github.com/PPIO/github-actions-runner-controller/blob/main/docs/design.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.