# 

https://docs.gitea.com/usage/actions/act-runner

## Binary Runner (for host/native workloads) 

### Create dedicated user
`sudo useradd -r -s /usr/sbin/nologin -m -c "Gitea Actions Runner" act_runner`

### Download latest version (0.2.12)
```
VERSION=0.2.12
sudo curl -sSLo /usr/local/bin/act_runner \
  https://dl.gitea.com/act_runner/${VERSION}/act_runner-${VERSION}-linux-amd64
sudo chmod +x /usr/local/bin/act_runner
```

### Create directories
```
sudo mkdir -p /etc/act_runner
sudo mkdir -p /var/lib/act_runner
```

### Generate & edit config
`/usr/local/bin/act_runner generate-config | sudo tee /etc/act_runner/config.yaml`

```
runner:
  file: .runner
  capacity: 1
  labels:
    - "native:host"
    - "linux-host:host"
    - "self-hosted:host"
    - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
    - "ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
```
The :host suffix tells the runner to execute jobs directly on the host instead of in Docker containers.

### Register the runner
```
cd /var/lib/act_runner_native
sudo -u act_runner /usr/local/bin/act_runner \
  --config /etc/act_runner/config.yaml \
  register \
  --no-interactive \
  --instance https://your-gitea.example.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name native-runner
  
sudo chown -R act_runner:act_runner /var/lib/act_runner
sudo chown -R act_runner:act_runner /etc/act_runner
```

### Create systemd service
`/etc/systemd/system/act_runner.service`

```
[Unit]
Description=Gitea Actions Runner (Native/Host)
Documentation=https://gitea.com/gitea/act_runner
After=network.target

[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner

[Install]
WantedBy=multi-user.target
```

```
sudo systemctl daemon-reload
sudo systemctl enable --now act_runner
```

### Rootless Podman Configuration for act_runner

#### 1. User Setup

The service user needs a proper home directory and shell:
```bash
sudo usermod -m -d /home/act_runner -s /bin/bash act_runner
sudo mkdir -p /home/act_runner
sudo chown act_runner:act_runner /home/act_runner
```

#### 2. User Namespace Mappings

Required for rootless containers to map UIDs/GIDs:
```bash
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 act_runner
podman system migrate
```

#### 3. Enable Linger and Podman Socket
```bash
sudo loginctl enable-linger act_runner
sudo -u act_runner XDG_RUNTIME_DIR=/run/user/$(id -u act_runner) systemctl --user enable --now podman.socket
```

#### 4. Configure act_runner

In `/etc/act_runner/config.yaml`:
```yaml
container:
  docker_host: unix:///run/user/<UID>/podman/podman.sock
```

Replace `<UID>` with output of `id -u act_runner`.

#### 5. Configure Registries

In `/etc/containers/registries.conf`:
```toml
unqualified-search-registries = ["docker.io", "docker.gitea.com"]
```

#### 6. systemd Unit Environment

Add to `/etc/systemd/system/act_runner.service` under `[Service]`:
```ini
Environment="XDG_RUNTIME_DIR=/run/user/%U"
```

#### 7. Apply Changes
```bash
sudo systemctl daemon-reload
sudo systemctl restart act_runner
```

## Docker Runner 

WIP