# How to Start a GitCaddy Runner

This guide explains how to set up and start a GitCaddy Actions runner (act_runner) to execute your CI/CD workflows.

## Prerequisites

- A Linux, macOS, or Windows machine
- Network access to your GitCaddy/Gitea instance
- (Optional) Docker installed for container-based workflows

## Quick Start

### 1. Download the Runner

Download the latest release from the [releases page](https://git.marketally.com/gitcaddy/act_runner/releases) or build from source:

```bash
git clone https://git.marketally.com/gitcaddy/act_runner.git
cd act_runner
make build
```

### 2. Register the Runner

Get a registration token from your GitCaddy instance:
- **Global runners**: Admin Area → Actions → Runners → Create Runner
- **Organization runners**: Organization Settings → Actions → Runners
- **Repository runners**: Repository Settings → Actions → Runners

Then register:

```bash
./act_runner register --no-interactive \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name my-runner \
  --labels linux,ubuntu-latest
```

### 3. Start the Runner

```bash
./act_runner daemon
```

## Configuration Options

### Runner Labels

Labels determine which jobs the runner can execute. Configure labels during registration or edit them in the admin UI.

Common labels:
- `linux`, `linux-latest` - Linux runners
- `windows`, `windows-latest` - Windows runners
- `macos`, `macos-latest` - macOS runners
- `ubuntu`, `ubuntu-latest` - Ubuntu-specific
- `self-hosted` - Self-hosted runners

### Running as a Service

#### Linux (systemd)

```bash
sudo cat > /etc/systemd/system/act_runner.service << 'SERVICE'
[Unit]
Description=GitCaddy Actions Runner
After=network.target

[Service]
Type=simple
User=runner
WorkingDirectory=/opt/act_runner
ExecStart=/opt/act_runner/act_runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl enable act_runner
sudo systemctl start act_runner
```

### Docker Support

For workflows that use container actions, ensure Docker is installed and the runner user has access:

```bash
sudo usermod -aG docker $USER
```

## Capabilities Detection

The runner automatically detects and reports:
- Operating system and architecture
- Available shells (bash, sh, powershell)
- Installed tools (node, python, go, etc.)
- Docker availability
- Disk space and network bandwidth

These capabilities help admins understand what each runner can handle.

## Troubleshooting

### Runner not connecting

1. Check network connectivity to your GitCaddy instance
2. Verify the registration token is valid
3. Check firewall rules allow outbound HTTPS

### Jobs not running

1. Verify runner labels match the job's `runs-on` requirement
2. Check runner is online in the admin panel
3. Review runner logs: `journalctl -u act_runner -f`

## More Information

- [act_runner Repository](https://git.marketally.com/gitcaddy/act_runner)
- [GitCaddy Documentation](https://git.marketally.com/gitcaddy/gitea)