furtka/docs/runner-setup.md

Forgejo Runner Setup

How to stand up a forgejo-runner so the CI workflow in .forgejo/workflows/ci.yml actually executes on every push.

The runner is a long-running daemon that polls the Forgejo instance for queued jobs and runs them in Docker containers.

Choosing a host

Option	Good for	Trade-off
Dedicated VPS	Production-ish CI that runs even when you're offline	Costs a few €/month; one more machine to maintain
Home server / NAS	Free; plenty of capacity	CI blocked if home network / power drops
Local dev machine	Quick to set up, fast runs	CI only works while the machine is on

Recommendation for now: home server or a cheap VPS. Don't use a laptop that suspends.

Install

Pick either the binary or the Docker container path. Docker is easier to upgrade.

Path A: Docker Compose (recommended)

On the chosen host, create ~/forgejo-runner/compose.yml:

services:
  runner:
    image: code.forgejo.org/forgejo/runner:6
    container_name: forgejo-runner
    restart: unless-stopped
    environment:
      - CONFIG_FILE=/data/config.yml
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - docker-in-docker
    command: /bin/sh -c "sleep 5; forgejo-runner daemon"

  docker-in-docker:
    image: docker:dind
    container_name: forgejo-runner-dind
    restart: unless-stopped
    privileged: true
    environment:
      - DOCKER_TLS_CERTDIR=
    command: dockerd -H tcp://0.0.0.0:2375 --tls=false

Path B: Binary

Download the latest release from https://code.forgejo.org/forgejo/runner/releases and drop it somewhere in $PATH:

wget https://code.forgejo.org/forgejo/runner/releases/download/v6.0.0/forgejo-runner-6.0.0-linux-amd64
chmod +x forgejo-runner-6.0.0-linux-amd64
sudo mv forgejo-runner-6.0.0-linux-amd64 /usr/local/bin/forgejo-runner

Register

1. In the Forgejo web UI: go to Site Administration → Actions → Runners → Create new Runner. Copy the registration token. (For a repo-scoped runner instead, use Repo Settings → Actions → Runners.)

2. Register from the runner host:

   forgejo-runner register \
     --instance https://forgejo.sourcegate.online \
     --token <TOKEN> \
     --name homebase-runner-1 \
     --labels docker,ubuntu-latest,self-hosted \
     --no-interactive
   

   This writes .runner (registration file) and config.yml into the current directory.

3. Start the daemon (Docker: docker compose up -d; binary: forgejo-runner daemon).

4. Verify the runner shows up as Idle in Forgejo's admin Runners page.

First CI run

Push any commit; the Actions tab on the repo should show the workflow running. If nothing happens:

• Confirm the runner is online (Forgejo admin → Actions → Runners).
• Check the workflow has labels that match the runner (runs-on: ubuntu-latest needs a runner registered with that label).
• Check the runner logs: docker logs forgejo-runner or the systemd journal.

Systemd unit (for the binary path)

[Unit]
Description=Forgejo Actions Runner
After=docker.service
Requires=docker.service

[Service]
ExecStart=/usr/local/bin/forgejo-runner daemon
WorkingDirectory=/var/lib/forgejo-runner
User=forgejo-runner
Restart=on-failure

[Install]
WantedBy=multi-user.target

Save as /etc/systemd/system/forgejo-runner.service, then sudo systemctl enable --now forgejo-runner.

Security notes

• The runner mounts /var/run/docker.sock which gives it root-equivalent access to the host. Run it on a machine you trust and nothing sensitive.
• Registration tokens are one-shot; a stolen token can't re-register after the runner is live.
• Prefer repo-scoped runners over instance-wide if you're sharing the runner with other repos you don't control.