Setup Forgejo Runner with rootless Podman on Fedora

When setting up Forgejo Runner on my Fedora machine based on the upstream documentation I ran into some minor issues. This post acts as a quick how-to to work around those.

First install the forgejo-runner binary from the Fedora repositories:

sudo dnf install forgejo-runner

This will create the user forgejo-runner, which we will use instead of the runner user from the upstream documentation.

Enable "linger" for the forgejo-runner user to ensure that the systemd environment for the user is being set up:

sudo loginctl enable-linger forgejo-runner

Enable the podman.socket for the forgejo-runner user:

sudo systemctl --machine forgejo-runner@.host --user enable --now podman.socket

Verify that the socket is enabled and note down its location:

$ sudo systemctl --machine forgejo-runner@.host --user status podman.socket
● podman.socket - Podman API Socket
     Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: disabled)
     Active: active (listening) since Wed 2026-10-07 11:53:06 CEST; 12min ago
 Invocation: 4e063ddb55d14bccb15644ecdf663581
   Triggers: ● podman.service
       Docs: man:podman-system-service(1)
     Listen: /run/user/971/podman/podman.sock (Stream)

Now the only step remaining is to update the Forgejo Runner configuration at /etc/forgejo-runner/config.yml by following the instructions from Forgejo Runner Configuration and Forgejo Runner Registration. I've chosen ubuntu-latest:docker://node:lts for my runner label for now and don't forget to prefix the Podman socket for docker_host with unix:// (e.g. unix:///run/user/971/podman/podman.sock in my case).

sudo vim /etc/forgejo-runner/config.yml

After that you can start your runner with

sudo systemctl enable --now forgejo-runner.service