Ansible Role: Forgejo Runner

Configures Forgejo Action runners on a KubeVirt VM using ansible-pull. The VM (podman, Ansible, mounts, etc.) and Forgejo runner registration are handled outside this repo—see fedora-infra/ansible.

Runner settings live in the OpenShift Secret forgejo-runner-config. A config watcher on the VM syncs that Secret to a vars file and triggers the same ansible-pull invocation as the daily cron (without the log file redirect). A daily cron at 1 AM runs the identical command with output appended to /home/fedora/ansible-pull.log. Both paths run the full role (watcher, cron, Zabbix, runner sync, podman secrets, systemd units). Override the command in roles/forgejo-runner/defaults/main.yml via ansible_pull_command or config_watcher_on_change_cmd if needed.

What runs (in order)

See roles/forgejo-runner/tasks/main.yml.

1. Debug — log that ansible-pull ran (timestamp)
2. Config watcher — systemd user service; watches the Secret over the Kubernetes API
3. Ansible-pull cron — daily at 1 AM
4. Zabbix agent (Fedora RPM, Hostname=forgejo-runnerhost-vm.forgejo-runnerhost.forgejo.svc.cluster.local, TLS PSK to in-cluster proxy) plus Forgejo cache checks via vfs.file.contents (see contrib/zabbix/ for the server template)
5. Sync runners — remove services/secrets for runners no longer in config
6. Podman secrets — .runner / config.yaml per runner
7. Systemd — forgejo-runner@.service template and enabled instances

Configuration

Production vars come from Secret forgejo-runner-config (key forgejo-runners-vars.yaml), synced to /home/fedora/forgejo-runners-vars.yaml. Example:

forgejo_instance_url: "http://forgejo-http.forgejo.svc.cluster.local:3000"

forgejo_runners:
  - name: "runner-1"
    labels:
      - "my-label"
    image: "code.forgejo.org/forgejo/runner:12"
    secret: "<40-char-hex>"

Defaults and fallbacks: group_vars/all/forgejo_runners.yml and roles/forgejo-runner/defaults/main.yml.

Zabbix agent (in forgejo-runners-vars.yaml from the Secret) must include the PSK when TLS is enabled. Either naming works:

# Role names:
zabbix_agent_tls_psk_key: "<hex key>"
zabbix_agent_tls_psk_identity: "Fedora"

# Or existing forgejo-runnerhost Secret keys (resolved automatically):
forgejo_runnerhost_zabbix_agent_psk: "<hex key>"
forgejo_runnerhost_zabbix_agent_identity: "Fedora"

Deployed Hostname defaults to forgejo-runnerhost-vm.forgejo-runnerhost.forgejo.svc.cluster.local and must match the Zabbix host visible name. Override with zabbix_agent_hostname if needed. Server lists the in-cluster proxy DNS name and 10.16.0.0/16.

Key paths

Path	Purpose
contrib/zabbix/template_forgejo_runner_vm.xml	Import into Zabbix server; watches user systemctl Forgejo runners, config watcher, and ansible-pull log mtime (see contrib/zabbix/README.md)
playbooks/ansible-pull.yml	Entry playbook (include_role: forgejo-runner → tasks/main.yml)
roles/forgejo-runner/tasks/main.yml	Task order for pull / watcher
roles/forgejo-runner/files/forgejo-runner-config-watcher.py	Secret watcher
roles/forgejo-runner/defaults/main.yml	ansible_pull_command, watcher env, Zabbix

Adding or removing runners

Change the forgejo-runner-config Secret in OpenShift. The watcher applies changes within seconds. Runners removed from config stop on the VM and appear offline in Forgejo; delete stale runners in Site Administration if you want them gone from the UI.

Troubleshooting

On the VM:

# Runner
systemctl --user status forgejo-runner@<runner-name>.service
journalctl --user -u forgejo-runner@<runner-name>.service -f

# Config watcher
systemctl --user status forgejo-runner-config-watcher.service
journalctl --user -u forgejo-runner-config-watcher.service -f

podman secret ls
cat /home/fedora/ansible-pull.log