gitea-dynamic-runner/docs/runner-protocol-roadmap.md

Gitea Runner 协议调度器路线

目标

长期形态不依赖 workflow_job webhook 发现工作。controller 本身作为 Gitea Runner 协议客户端注册，并声明 self-hosted、pod 和 vm labels；它只在后端存在可用容量 时领取 task，然后将该 task 交给一个一次性 Pod 或 microVM 执行。

Gitea RunnerService
        │ Register / Declare / FetchTask
        ▼
dynamic-runner scheduler
        │ 已领取的 task + lease
        ├── Pod executor
        └── microVM executor
                │ logs / state / result
                └──────────────────────► Gitea

这与“收到 webhook 后临时注册另一个 act_runner”不同。FetchTask 已经完成任务分配， 不能再期待 Gitea 把同一个 task 分配给随后启动的 runner。协议调度器必须让 executor 执行已经领取的 task，并继续完成日志、状态、心跳、取消和最终结果上报。

设计约束

• 对 workflow 的接口保持 [self-hosted, pod] 和 [self-hosted, vm] 不变。
• scheduler 在没有对应 backend 容量时不领取 task，避免本地形成不可控积压。
• 每个 executor 只执行一个 task，完成后销毁。
• SPIFFE 身份从实际领取的 task 的 repository 和 job name 派生，不需要 queued 与 in-progress webhook 的二阶段关联。
• scheduler 的 runner registration credential 不进入 executor；executor 只得到执行 当前 task 所需的短期 lease/capability。
• task ACK、心跳和结果必须能够跨 scheduler 重启恢复；NATS 可以继续作为内部 handoff， 但不是 Gitea 任务事实来源。
• Pod 与 VM 共享 task/executor 协议，只有环境创建和销毁实现不同。

实现顺序

1. 固定当前 Gitea 版本所使用的 RunnerService protobuf 与 act_runner 版本，记录兼容 范围并建立协议契约测试。
2. 实现只注册、Declare labels 和容量感知 FetchTask 的 scheduler spike，暂不执行 task。
3. 从 act_runner 提取或复用 task 执行与日志上报能力，定义 scheduler 到 executor 的 单任务协议。
4. 首先接入 Pod executor，验证成功、失败、取消、超时和 scheduler 重启。
5. 接入 microVM executor，并复用同一 task 协议和身份派生逻辑。
6. 双轨运行并验证后，移除 webhook receiver、临时 runner 注册和 identity binding subject。

Bootstrap 实现的退出条件

只有同时满足以下条件才能删除 webhook 路径：

• scheduler 能通过 RunnerService 稳定领取并执行 Pod/VM task；
• Gitea UI 中的实时日志、取消、超时和结论与官方 runner 行为一致；
• scheduler 重启不会丢失已领取 task，也不会重复执行；
• SPIFFE 身份只来自实际领取 task；
• 同一套 workflow 无需修改 runs-on 即可从 bootstrap 迁移。