incuse

Ephemeral GitHub Actions runners on Incus VMs.

What

A single-host orchestrator that owns one GitHub Actions Runner Scale Set per configured CPU/memory/disk/architecture class. It maintains GitHub's desired number of ephemeral JIT runners by launching fresh Incus VMs. Each VM powers itself off when the runner exits; a reaper cleans up stragglers.

graph LR
    GH[GitHub Actions scale sets] -->|long-poll| O[incuse]
    O -->|mint JIT| GH
    O -->|launch VM with cloud-init| I[Incus]
    I --> V1[VM] & V2[VM]
    V1 -->|run runner.sh, then poweroff| GH

Loading

Designed to run as a systemd service on the same host as the Incus daemon, talking to it over the local Unix socket. HTTPS+cert is also supported for off-host deployments.

Status

Early. See the project plan for the active phase.

Install

On a host running Incus, with the incuse system user pre-created (or letting install.sh create it):

bash deploy/systemd/install.sh ./bin/incuse
# edit /etc/incuse/config.yaml, drop a chmod-600 PAT at /etc/incuse/github.pat
systemctl enable --now incuse

Full walkthrough: docs/deployment.md. Day-2 ops: docs/operations.md.

Build

make            # build ./bin/incuse
make test       # go test -race ./...
make lint       # golangci-lint run

License

MIT — see LICENSE.