From 5b44022f9922ea6e5ad5e4e2dcf0d636b2dfeb14 Mon Sep 17 00:00:00 2001
From: thomasabishop <thomasabishop@tuta.com>
Date: Fri, 15 Aug 2025 16:14:23 +0100
Subject: [PATCH] content: add entry on Forgejo runners

---
 zk/Configuring_Forgejo_runners.md | 84 +++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 zk/Configuring_Forgejo_runners.md

diff --git a/zk/Configuring_Forgejo_runners.md b/zk/Configuring_Forgejo_runners.md
new file mode 100644
index 0000000..fcedf1a
--- /dev/null
+++ b/zk/Configuring_Forgejo_runners.md
@@ -0,0 +1,84 @@
+---
+tags:
+  - git
+  - forgejo
+  - servers
+---
+
+https://forgejo.systemsobscure.net/admin/actions/runners/
+
+# Configuring Forgejo runners
+
+When you create a Forgejo Action, this alone is not sufficient for the Action to
+run. You also have to configure a runner for an installation or a specific repo.
+The is a Docker container which does the actual computation.
+
+## Installing `forgejo-runner`
+
+Before you can set up a specific runner for a repo, you need to install the
+`forgejo-runner` software initially.
+
+```sh
+wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v9.0.3/forgejo-runner-9.0.3-linux-amd64
+chmod +x forgejo-runner
+```
+
+You then need to create a user for the runner that will use Docker.
+
+```sh
+ useradd --create-home runner
+ usermod -aG docker runner
+```
+
+Start the service or create a `systemd` service so it always starts on reboot.
+
+> My `systemd` service file is saved at
+> /etc/systemd/system/forgejo-runner.service
+
+```sh
+forgejo runner-daemon
+```
+
+## Creating a runner for your repos
+
+There is a CLI tool to assist:
+
+```sh
+forgejo-runner register
+```
+
+Example inputs:
+
+```
+INFO Registering runner, arch=amd64, os=linux, version=v9.0.3.
+WARN Runner in user-mode.
+INFO Enter the Forgejo instance URL (for example, https://next.forgejo.org/):
+https://forgejo.systemsobscure.net
+INFO Enter the runner token:
+redacted
+INFO Enter the runner name (if set empty, use hostname: self-host-server):
+self-host-server
+INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-20.04:docker://node:20-bookworm,ubuntu-18.04:docker://node:20-bookworm):
+ ubuntu-latest
+INFO Registering runner, name=sysobs-forgejo-runner, instance=https://forgejo.systemsobscure.net, labels=[ubuntu-20.04:docker://node:20-bookworm].
+DEBU Successfully pinged the Forgejo instance server
+INFO Runner registered successfully.
+```
+
+Get the runner token from "Site Settings" > "Actions" > "Runners".
+
+The OS image (`ubuntu-latest`) should be sufficient for most of my operations. I
+can then add specific software as containers within the individual action files,
+e.g.:
+
+```yml
+name: Deploy Blog
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    container: node:18
+    steps: ...
+```