Skip to content

incus-gh-runner

incus-gh-runner is a controller that runs one-job GitHub Actions runners in ephemeral Incus virtual machines. It presents them to GitHub as a runner scale set, provisioning and tearing down a fresh VM for each job, and it deploys as a systemd service on a Linux host.

Requirements

  • Incus 7.0 or newer.
  • A dedicated Linux host. The controller's identity needs incus-admin group membership, which is root-equivalent on that host.
  • A GitHub App or personal access token authorized for the configured repository or organization.

See Deploy to production for the full host and GitHub prerequisites.

Where to go

Deploy it Deploy to production walks through the end-to-end production deployment: host prerequisites, GitHub App or PAT setup, configuration, and installing the systemd unit.

Operate it Operate and troubleshoot covers day-2 operations — checking runner state, reading logs, restarting the service, and troubleshooting.

Runner images Build a hardened runner image covers building your own guest VM image against the guest contract, with the hardening baseline the project recommends.

Understand it How incus-gh-runner works explains the capacity model, runner lifecycle, the controller's cleanup boundary over Incus resources, its failure-handling philosophy, and its security model.

Look up facts

  • Configuration reference — every config key, environment variable, CLI flag, and how they take precedence over each other.
  • Guest contract reference — the controller-guest interface: payload and status file schemas, serial console lines, and instance metadata keys.
  • Job proofs reference — the version 1 job machine proof: DSSE envelope, payload schema, size limits, and the key-ID rule.