From 0bd4549af06e13d885b2bec250cd61f5a4451c4f Mon Sep 17 00:00:00 2001
From: "dolgolyov.alexei" <dolgolyov.alexei@gmail.com>
Date: Tue, 7 Apr 2026 19:41:35 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20add=20gitea-runner.md=20=E2=80=94=20Act?=
 =?UTF-8?q?=20Runner=20worker=20capacity=20on=20TrueNAS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

How to configure parallel job capacity for Gitea Act Runner:
the CONFIG_FILE env var requirement, custom config.yaml mount,
and capacity tuning.
---
 gitea-runner.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 gitea-runner.md

diff --git a/gitea-runner.md b/gitea-runner.md
new file mode 100644
index 0000000..787228b
--- /dev/null
+++ b/gitea-runner.md
@@ -0,0 +1,39 @@
+# Gitea Act Runner — Configuring Worker Capacity (TrueNAS)
+
+## Problem
+
+The default Gitea Act Runner (`gitea/act_runner`) runs with `capacity: 1`, meaning only one job at a time. Setting `GITEA_RUNNER_RUNNER__CAPACITY` env var or placing a `config.yaml` in the app data directory does **not** work on its own.
+
+## Root Cause
+
+The runner's entrypoint (`run.sh`) only passes `--config` to `act_runner daemon` when the `CONFIG_FILE` environment variable is explicitly set. Without it, the runner ignores any config file, even if it exists at `/data/config.yaml`.
+
+## Solution
+
+1. **Create the config file** in the app data directory (mounted as `/data` inside the container):
+
+   ```yaml
+   # /mnt/system_pool/app_data/gitea-runner/config.yaml
+   runner:
+     capacity: 6
+   ```
+
+2. **Set the `CONFIG_FILE` environment variable** in TrueNAS:
+
+   Go to **TrueNAS UI → Apps → Gitea Act Runner → Edit → Extra Environment Variables** and add:
+
+   ```
+   CONFIG_FILE=/data/config.yaml
+   ```
+
+3. **Restart the app.**
+
+## Verification
+
+Check the runner logs after restart — concurrent jobs should now show `maxParallel` matching your capacity, and multiple tasks should run simultaneously.
+
+## Notes
+
+- `capacity` controls how many **separate jobs** the runner handles concurrently
+- `maxParallel` in logs refers to parallelism within a single job's matrix strategy, not the runner capacity
+- To generate a full default config for reference: `act_runner generate-config`