# 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
```