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

  • A dedicated, single-purpose Incus 7.0 or newer compute host.
  • A controller machine with either root-equivalent local incus-admin socket access or HTTPS access through an exact server-certificate pin and a client certificate restricted to the runner project. The HTTPS controller can run on a separate Linux machine.
  • 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: separate controller and compute-host requirements, local socket or pinned HTTPS transport, Incus preparation, GitHub App or PAT setup, configuration, and the systemd unit.

Operate it Operate and troubleshoot covers day-2 operations: checking runner state, reading logs, rotating HTTPS credentials, 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.