.gitignore | ||
authorized_keys | ||
build-forgejorunner-template.sh | ||
build-github-runner-kvm-ubuntu-latest-qcow.sh | ||
clone-and-register.sh | ||
forgejo-runner | ||
forgejo-runner-3.5.0-linux-amd64 | ||
forgejo-runner.service | ||
README.md | ||
register-forgejo-runner.sh |
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