Creating a new ForgeJo Runner Host

Machine Setup

1. Install Ubuntu (24.04)

For example on the Hetzner cloud.

2. Create a new user for the runner

Since we don't want to the new forgejo runner to be root on out machine, we create a new user for it:

# As root
useradd -s /bin/bash --create-home forgejo-runner
loginctl enable-linger forgejo-runner

3. Install podman (rootless)

# As root
apt install -y podman
echo "forgejo-runner:10000:12000" >> /etc/subuid
echo "forgejo-runner:10000:12000" >> /etc/subgid

Enable Podman docker-socket on user

# As root
apt install -y systemd-container
machinectl shell --uid forgejo-runner # <-- This is basically "sudo -Hi XXX" but makes sure the systemd container is switched too.

systemctl enable --user podman.socket
echo 'export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock' >> ~/.profile

Automatic podman cleanup on reboot

crontab -e

@reboot podman system cleanup --all --force

4. Install the forgejo-runner

# As forgejo-runner
# Verify these URLs are still the version you want to install!!!
DOWNLOAD_URL="https://code.forgejo.org/forgejo/runner/releases/download/v5.0.4/forgejo-runner-5.0.4-linux-amd64"
SIG_URL="https://code.forgejo.org/forgejo/runner/releases/download/v5.0.4/forgejo-runner-5.0.4-linux-amd64.asc"
gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710 # Installs the signing key used by forgejo for their releases
wget -O forgejo-runner "$DOWNLOAD_URL"
wget -O forgejo-runner.asc "$SIG_URL"
gpg --verify forgejo-runner.asc forgejo-runner
# The output should now contain the following:
# Good signature from "Forgejo <contact@forgejo.org>"
#		aka "Forgejo Releases <release@forgejo.org>"

mkdir -p ~/.local/bin
mv ./forgejo-runner ~/.local/bin/forgejo-runner
chmod 750 ~/.local/bin/forgejo-runner

5. Configure and register the forgejo-runner

The official runner registration is here Or, if you're volunteering another runner for our instance, please contact us to receive the necessary registration information. :)

# As forgejo-runner
forgejo-runner generate-config > config.yml

# We're about to enter secrets into the terminal, disable history:
set +o history
RUNNER_INST_URL="https://git.forsaken-ashbirds.net"
RUNNER_NAME="<PLEASE ENTER A UNIQUE NAME FOR YOUR RUNNER HERE!!!>"
RUNNER_TOKEN="<The token from the UI>"
RUNNER_LABELS="ubuntu-24.04,docker,podman,self-hosted" # Update these labels if you intend to change stuff!

# Re-enable history :)
set -o history
forgejo-runner register --instance "$RUNNER_INST_URL" --name "$RUNNER_NAME" --token "$RUNNER_TOKEN" --labels "$RUNNER_LABELS" --no-interactive
# You should see the following afterwards:
# INFO Runner registered successfully

Check the runner is working

# As forgejo-runner
mkdir -p ~/.config/systemd/user
# Download the file "docs/forgejo-runner.service" from this repository to "~/.config/systemd/user"
systemctl --user enable --now forgejo-runner

Go into Forgejo and check that your runner is shown as UP.

3.3 KiB Raw Blame History