---
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: ...
```