FHLS Runner Academy

01The mental model

runs-on: [self-hosted, fhls]

02Wire a new repo to the box

Substitute NEWREPO, pick N = next free /opt/actions-runner-N. Step 1 runs on any of your machines; the rest on the box.

1. Mint a registration token (valid 1 hour)

   macbook / macmini / pccopy

   TOKEN=$(gh api -X POST repos/jojomojo786/NEWREPO/actions/runners/registration-token --jq .token)

2. Install the runner software

   Match the version the existing runners report (/opt/actions-runner/bin/Runner.Listener --version); auto-update keeps it current afterwards.

   on FHLS-Server-Hetznercopy

   mkdir -p /opt/actions-runner-N && cd /opt/actions-runner-N
   curl -sL -o r.tar.gz https://github.com/actions/runner/releases/download/v2.336.0/actions-runner-linux-x64-2.336.0.tar.gz
   tar xzf r.tar.gz && rm r.tar.gz
   chown -R github-runner:github-runner /opt/actions-runner-N

3. Register — keep the labels identical

   on FHLS-Server-Hetznercopy

   sudo -u github-runner ./config.sh --unattended \
     --url https://github.com/jojomojo786/NEWREPO \
     --token "$TOKEN" \
     --name FHLS-NEWREPO \
     --labels hetzner,debian-12,fhls \
     --work _work

4. Bind-mount _work onto /home — before the first job

   The runner tooling knows nothing about this. Skip it and the workspace lands on the 160 GB root disk — flip the toggle off in the simulator and press “Runaway build” to watch what that costs.

   on FHLS-Server-Hetznercopy

   mkdir -p /home/github-runner/FHLS-NEWREPO-work
   chown github-runner:github-runner /home/github-runner/FHLS-NEWREPO-work
   
   UNIT=$(systemd-escape -p --suffix=mount /opt/actions-runner-N/_work)
   cat > "/etc/systemd/system/$UNIT" <<EOF
   [Unit]
   Description=GitHub Actions runner N workspace on /home
   RequiresMountsFor=/home
   Before=actions.runner.jojomojo786-NEWREPO.FHLS-NEWREPO.service
   
   [Mount]
   What=/home/github-runner/FHLS-NEWREPO-work
   Where=/opt/actions-runner-N/_work
   Type=none
   Options=bind
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   SVC=actions.runner.jojomojo786-NEWREPO.FHLS-NEWREPO.service
   mkdir -p "/etc/systemd/system/$SVC.d"
   printf '[Unit]\nRequires=%s\nAfter=%s\n' "$UNIT" "$UNIT" \
     > "/etc/systemd/system/$SVC.d/workspace-mount.conf"
   
   systemctl daemon-reload && systemctl enable --now "$UNIT"

5. Cleanup hooks, then install & start the service

   on FHLS-Server-Hetznercopy

   # per-job workspace cleanup — same hook the other runners use
   echo 'ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/github-runner-hooks/cleanup-workspace.sh' \
     >> /opt/actions-runner-N/.env
   
   # daily stale-cleanup hardcodes its roots — add "/opt/actions-runner-N/_work" to:
   nano /opt/github-runner-hooks/cleanup-stale-workspaces.sh
   
   # growing caches belong on md3 too (npm cache, Playwright browsers, runner logs) —
   # jobs' HOME is the install dir, so npm ci would otherwise fatten the root disk
   mkdir -p /home/github-runner/runner-N-cache
   chown github-runner:github-runner /home/github-runner/runner-N-cache
   for d in .npm .cache _diag; do
     mkdir -p /home/github-runner/runner-N-cache/$d
     chown github-runner:github-runner /home/github-runner/runner-N-cache/$d
     ln -s /home/github-runner/runner-N-cache/$d /opt/actions-runner-N/$d
   done
   
   cd /opt/actions-runner-N
   ./svc.sh install github-runner && ./svc.sh start

6. Verify, then wire the repo

   macbookcopy

   gh api repos/jojomojo786/NEWREPO/actions/runners \
     --jq '.runners[] | "\(.name) \(.status) \([.labels[].name]|join(","))"'
   # expect: FHLS-NEWREPO online self-hosted,Linux,X64,hetzner,debian-12,fhls

   Workflows use runs-on: [self-hosted, fhls]; secrets are per-repo too — gh secret set NAME -R jojomojo786/NEWREPO.

03Incident drills

Every symptom below actually happened on this setup. Diagnose it faster than the first time.

04Verify & debug cheatsheet

gh api repos/jojomojo786/REPO/actions/runners --jq '.runners[] | "\(.name): \(.status) busy=\(.busy)"'

gh api repos/jojomojo786/REPO/actions/runs/RUN_ID/jobs --jq '.jobs[] | "\(.name) => \(.conclusion) on \(.runner_name)"'
gh api repos/jojomojo786/REPO/actions/runs/RUN_ID/timing   # "billable": {} → self-hosted, free

journalctl -u actions.runner.jojomojo786-REPO.RUNNER_NAME.service -n 30 --no-pager -o cat
findmnt /opt/actions-runner-N/_work    # source must say md3
df -h / /home                          # root should hold ~20%