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