Forgejo Runner — Management Reference22.09.26

# Forgejo Runner — Management Reference

> Operations reference for the Forgejo Actions runner on `code.salamander-jewelry.net`.
> Covers the mechanics (binary vs. executor vs. Docker), where the config lives,
> adding/updating a runner, and how to verify changes actually took effect.

## 1. The mechanics — three pieces

| Piece | What it is | Always needed? |
|---|---|---|
| `forgejo-runner` (binary) | Worker daemon: polls the Forgejo instance, picks up jobs, executes them, streams logs/status back | **yes** |
| Executor (per `label:type`) | Decides HOW a job's steps run: `host` = directly on the host, `docker://image` = in a spawned container | depends on label |
| Docker daemon | Only needed when the label uses a `docker` executor | only for docker labels |

Job flow:

```
push → Forgejo sees .forgejo/workflows/*.yaml → schedules job
     → forgejo-runner daemon (polling) picks it up
     → matches runs-on label against its registered labels
     → docker label: Docker daemon pulls image, starts container
     → runs each step (git clone, rsync, …) inside, logs streamed back
     → reports finish → container removed
```

Our setup: all in-repo workflows (`code/*/.forgejo/workflows/deploy.yaml`) use
`runs-on: docker3` → the runner carries a docker-typed label `docker3`.

## 2. Where the config lives (this host)

- Service: `forgejo-runner.service`, runs as user `git`, `WorkingDirectory=/home/git`
  (base unit at `/etc/systemd/system/forgejo-runner.service`).
- `systemd-detect` gotcha: starting the daemon **without `-c`** loads only the
  default filename (`config.yaml`) in its working directory. Editing a different
  name (e.g. `config.yml`) silently does nothing.
- Currently we make the path explicit via a drop-in override so the edited file
  is unambiguous:
  - `/etc/systemd/system/forgejo-runner.service.d/override.conf`:
    ```ini
    [Service]
    ExecStart=
    ExecStart=/usr/local/bin/forgejo-runner daemon -c /home/git/config.yml
    ```
- Config file: `/home/git/config.yml` (generated once by
  `forgejo-runner generate-config`). Key settings:
  ```yaml
  runner:
    file: .runner        # registration identity (uuid/token/labels)
    capacity: 5          # max concurrent jobs this daemon runs
    labels: []           # empty → labels come from the .runner file
  ```
- Registration identity: `/home/git/.runner` (JSON). This holds the real labels
  (e.g. `docker3`) because `labels: []` in the config defers to it. Deleting the
  `.runner` file registers a brand-new runner.

## 3. Determining the config location (never assume)

```bash
ps -ef | grep -v grep | grep forgejo-runner   # shows -c <path> if set
systemctl cat forgejo-runner                  # ExecStart + WorkingDirectory
readlink /proc/<PID>/cwd                      # cwd of the daemon
/usr/local/bin/forgejo-runner daemon --help   # default --config filename
ls -la <workdir>                              # confirm which file really exists
```

## 4. Change capacity (or any setting)

```bash
sed -i 's/^  capacity: 1$/  capacity: 5/' /home/git/config.yml
grep -n '^  capacity:' /home/git/config.yml
systemctl restart forgejo-runner
```

Capacity applies **only after a restart**. Not restartable via systemd? Find the
start mechanism first (child of PID 1 → `systemctl list-units`, `/etc/rc.local`, …).

## 5. Add a new runner (binary + systemd)

1. Instance admin → Admin → Actions → Runners → Create a Runner → copy token
   (shown once only, store in password manager, never in git).
2. On the host:
   ```bash
   wget -O /usr/local/bin/forgejo-runner \
     https://code.forgejo.org/forgejo/runner/releases/download/<V>/forgejo-runner-<V>-linux-amd64
   chmod +x /usr/local/bin/forgejo-runner
   # label must match what workflows use (our case: docker3) + the job image
   forgejo-runner register --instance https://code.salamander-jewelry.net \
     --token <REG_TOKEN> --name <hostname> --no-interactive \
     --labels 'docker3:docker://ghcr.io/catthehacker/ubuntu:act-22.04'
   ```
3. Config + systemd unit (see §2 pattern), `systemctl enable --now forgejo-runner`,
   verify online in Admin → Actions → Runners.

## 6. Update the runner binary

```bash
systemctl stop forgejo-runner
wget -O /usr/local/bin/forgejo-runner \
  https://code.forgejo.org/forgejo/runner/releases/download/<V>/forgejo-runner-<V>-linux-amd64
chmod +x /usr/local/bin/forgejo-runner
/usr/local/bin/forgejo-runner --version
systemctl start forgejo-runner
```

Version rule: runner major version should match the Forgejo server major
(server version: Admin → About or `/api/v1/version`).

## 7. Multiple registrations on one host (same binary + Docker)

- Each registration = its own `.runner` file (own uuid/token) = separate runner
  in the UI.
- One binary and one Docker daemon can serve many instances.
- Per-instance requirements: separate `.runner`, separate working dir / `runner.file`,
  separate systemd unit, unique `--name`.
- Want just more parallelism? Don't register duplicates — raise `capacity` instead.
  `capacity: 5` on one daemon = 5 simultaneous container jobs.

## 8. Verify capacity is actually applied

Static:
```bash
ps -ef | grep -v grep | grep forgejo-runner    # shows -c <path>
grep -n '^  capacity:' <loaded-config>         # must print the new value
journalctl -u forgejo-runner -n 30            # clean start, no config errors
```

Functional (the real proof): trigger ≥5 jobs at once (5-element matrix or pushes
to several repos within seconds), then while they run:
```bash
docker ps | grep -i "act-\|task-" | wc -l
```
5 running containers = parallel, capacity live. 1 = jobs still queueing (config
not loaded → check §2/§3).

Anonymous

Forgejo Runner — Management Reference22.09.26

Information Epoch 1794528643