.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.
It 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