Build and Set Up a Github-compatible Forgejo Runner on Proxmox

In order for Forgejo workflows to be usable out-of-the-box with as many actions as possible, it is useful to habe a runner that supports the same tools as the standard Github runner ubuntu-latest. Github does publish the code they use to build their runner images at https://github.com/actions/runner-images, but that repo cannot be used directly to build KVM images for use with Proxmox.

The fork https://github.com/fffonion/runner-images-kvm has the necessary changes to enable building such images.

Building the KVM runner image

The script build-github-runner-kvm-ubuntu-latest-qcow.sh installs the necessary package dependencies to build a KVM image, Hashicorp Packer (in the latest version still licensend under the MPL), and builds the Ubuntu image (24.04 at the moment). The resulting image github-runner-image-ubuntu-24.04.qcow2 can then be used in Proxmox, or any other KVM based virtualization solution.

Creating a Proxmox template VM

The script build-forgejorunner-template.sh runs on a Proxmox cluster host. It runs the build script via SSH on a builder VM (that has nested virtualization enabled), in case of CCCHH a Debian 12 install. It then copies the resulting VM to the Proxmox host.

Note: at the time of this writing, the builder VM needs at least 16 cores to satisfy the KVMn config for the VM being built. The resulting disk is 80 GB, with about 45 GB in use. You will need enough disk space on your cluster for at least three copies of this. Building the image takes anywhere between 30 and 180 minutes, depending on your host and your download speed.

It then creates a template VM from the image, installing https://code.forgejo.org/forgejo/runner and some helper scripts.

Cloning the Template VM

You can clone the template VM from the GUI, or through qm clone. Make the necessary changes and boot the VM.

You can clone and register the runner using the script clone-and-register.sh.

Registering the Runner

You can run the registration by logging in to the VM either on the console or through SSH, by running forgejo-runner register as the forgejo-runner user, or by invoking /usr/local/bin/register-forgejo-runner, supplying the registration token as the first argument.

You can run the registration from the Proxmox cluster host:

qm guest exec 150 -- sudo -iu forgejo-runner register-forgejo-runner iwKWPwI3H6h93kRuhXqMPcmCR2OGpgZlDT3mufGb
qm guest exec 150 -- systemctl restart forgejo-runner