gitcaddy-runner/README.md

# GitCaddy Runner

A Gitea Actions runner with enhanced capability detection and reporting for AI-friendly workflow generation.

GitCaddy Runner is a hard fork of Gitea's act_runner, rebranded and enhanced with automated capability detection to enable AI tools to generate compatible workflows based on available resources.

## Features

- **Automated Capability Detection**: Automatically identifies OS, architecture, installed tools, and available resources
- **Concurrent Job Execution**: Configure runner capacity to handle multiple jobs simultaneously
- **Docker Support**: Full support for Docker and Docker Compose workflows
- **Xcode Integration**: Detects Xcode installations, SDKs, and simulators on macOS
- **Tool Detection**: Identifies installed tools (Node.js, Python, .NET, Go, Ruby, Swift, etc.)
- **AI-Friendly API**: Exposes capabilities through Gitea's API for automated workflow generation
- **Cache Support**: Built-in workflow cache support for faster builds

## Installation

### Pre-built Binaries

Download the latest release for your platform from the [releases page](https://git.marketally.com/gitcaddy/gitcaddy-runner/releases):

**macOS:**
```bash
# Apple Silicon (M1/M2/M3/M4)
curl -L -o gitcaddy-runner https://git.marketally.com/gitcaddy/gitcaddy-runner/releases/download/v1.0.0/gitcaddy-runner-1.0.0-darwin-arm64
chmod +x gitcaddy-runner

# Intel
curl -L -o gitcaddy-runner https://git.marketally.com/gitcaddy/gitcaddy-runner/releases/download/v1.0.0/gitcaddy-runner-1.0.0-darwin-amd64
chmod +x gitcaddy-runner
```

**Linux:**
```bash
# x86_64
curl -L -o gitcaddy-runner https://git.marketally.com/gitcaddy/gitcaddy-runner/releases/download/v1.0.0/gitcaddy-runner-1.0.0-linux-amd64
chmod +x gitcaddy-runner

# ARM64
curl -L -o gitcaddy-runner https://git.marketally.com/gitcaddy/gitcaddy-runner/releases/download/v1.0.0/gitcaddy-runner-1.0.0-linux-arm64
chmod +x gitcaddy-runner
```

**Windows:**
```powershell
# Download the Windows executable
# https://git.marketally.com/gitcaddy/gitcaddy-runner/releases/download/v1.0.0/gitcaddy-runner-1.0.0-windows-amd64.exe
```

### Build from Source

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

## Quick Start

### 1. Enable Gitea Actions

In your Gitea `app.ini`:

```ini
[actions]
ENABLED = true
```

### 2. Generate Configuration

```bash
./gitcaddy-runner generate-config > config.yaml
```

### 3. Configure the Runner

Edit `config.yaml` to customize settings. **Important configuration options:**

```yaml
log:
  level: info

runner:
  file: .runner
  capacity: 2  # Number of concurrent jobs (default: 1)
  timeout: 3h
  shutdown_timeout: 3m  # Grace period for running jobs on shutdown
  insecure: false
  fetch_timeout: 5s
  fetch_interval: 2s
  labels:
    - "ubuntu-latest:docker://node:16-bullseye"
    - "ubuntu-22.04:docker://node:16-bullseye"

cache:
  enabled: true
  dir: ""

container:
  network: ""
  privileged: false
  options: ""
  valid_volumes: []
  docker_host: ""
  force_pull: false

host:
  workdir_parent: ""
```

#### Capacity Configuration

The `capacity` setting controls how many jobs the runner can execute simultaneously:

- **Default**: 1 (one job at a time)
- **Recommended**: 2-4 for multi-core systems
- **Considerations**:
  - Each job consumes CPU, memory, and disk I/O
  - iOS/macOS builds are resource-intensive (start with 2)
  - Lighter builds (Node.js, Go) can handle higher capacity (4-6)
  - Monitor system load and adjust accordingly

**Example for different workloads:**

```yaml
# Light builds (web apps, APIs)
runner:
  capacity: 4

# Mixed builds
runner:
  capacity: 2

# Heavy builds (iOS/macOS, large containers)
runner:
  capacity: 1
```

### 4. Register the Runner

```bash
./gitcaddy-runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name my-runner \
  --labels ubuntu-latest:docker://node:16-bullseye
```

The registration token can be obtained from:
- Gitea Admin Panel > Actions > Runners
- Or repository Settings > Actions > Runners

### 5. Start the Runner

**Important:** Always specify the config file path with `-c` flag:

```bash
./gitcaddy-runner daemon -c config.yaml
```

**Without the `-c` flag, the runner will use default settings and ignore your config.yaml!**

## Running as a Service

### macOS (launchd)

Create `~/Library/LaunchAgents/com.gitcaddy.runner.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitcaddy.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/gitcaddy-runner</string>
        <string>daemon</string>
        <string>-c</string>
        <string>/path/to/config.yaml</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/runner/directory</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/path/to/runner.log</string>
    <key>StandardErrorPath</key>
    <string>/path/to/runner.err</string>
</dict>
</plist>
```

Load the service:

```bash
launchctl load ~/Library/LaunchAgents/com.gitcaddy.runner.plist
```

### Linux (systemd)

Create `/etc/systemd/system/gitcaddy-runner.service`:

```ini
[Unit]
Description=GitCaddy Actions Runner
After=network.target

[Service]
Type=simple
User=runner
WorkingDirectory=/home/runner/gitcaddy-runner
ExecStart=/home/runner/gitcaddy-runner/gitcaddy-runner daemon -c /home/runner/gitcaddy-runner/config.yaml
Restart=always
RestartSec=10

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

Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable gitcaddy-runner
sudo systemctl start gitcaddy-runner
```

### Windows (NSSM or Native Service)

GitCaddy Runner has native Windows service support. When running as a service, it automatically detects the Windows Service Control Manager (SCM) and handles stop/shutdown signals properly.

**Option 1: Using NSSM (Recommended)**

Install NSSM via Chocolatey:

```powershell
choco install nssm -y
```

Create the service:

```powershell
# Install the service
nssm install GiteaRunnerSvc C:\gitea-runner\gitcaddy-runner.exe daemon --config C:\gitea-runner\config.yaml

# Set working directory
nssm set GiteaRunnerSvc AppDirectory C:\gitea-runner

# Set environment variables
nssm set GiteaRunnerSvc AppEnvironmentExtra HOME=C:\gitea-runner USERPROFILE=C:\gitea-runner

# Configure auto-restart on failure
sc failure GiteaRunnerSvc reset=86400 actions=restart/60000/restart/60000/restart/60000

# Start the service
sc start GiteaRunnerSvc
```

**Option 2: Native sc.exe (requires wrapper)**

Create a wrapper batch file `C:\gitea-runner\start-runner.bat`:

```batch
@echo off
set HOME=C:\gitea-runner
set USERPROFILE=C:\gitea-runner
cd /d C:\gitea-runner
C:\gitea-runner\gitcaddy-runner.exe daemon --config C:\gitea-runner\config.yaml
```

**Service Management:**

```powershell
# Check service status
sc query GiteaRunnerSvc

# Start service
sc start GiteaRunnerSvc

# Stop service
sc stop GiteaRunnerSvc

# View service logs (if using NSSM with log rotation)
Get-Content C:\gitea-runner\logs\runner.log -Tail 50
```

**Environment Variables for Windows Services:**

| Variable | Description | Example |
|----------|-------------|---------|
| `GITEA_RUNNER_SERVICE_NAME` | Override service name detection | `GiteaRunnerSvc` |

## Capability Detection

GitCaddy Runner automatically detects and reports system capabilities:

### Platform Information
- Operating system (darwin, linux, windows)
- Architecture (amd64, arm64)

### Container Runtime
- Docker availability and version
- Docker Compose support
- Container runtime type

### Development Tools
- Node.js, npm, yarn
- Python, pip
- Go
- .NET
- Ruby
- Rust
- Java
- Swift (macOS)
- Git, Make

### macOS-Specific
- Xcode version and build
- Available SDKs (iOS, macOS, tvOS, watchOS, visionOS)
- Simulators
- Code signing tools (codesign, pkgbuild)
- Package managers (Homebrew, CocoaPods, Fastlane)

### System Resources
- CPU cores
- Load average
- Disk space and usage
- Network bandwidth

### Example Capabilities Output

```json
{
  "os": "darwin",
  "arch": "arm64",
  "capacity": 2,
  "docker": true,
  "docker_compose": true,
  "container_runtime": "docker",
  "xcode": {
    "version": "15.2",
    "build": "15C500b",
    "sdks": ["iOS 17.2", "macOS 14.2"]
  },
  "tools": {
    "node": ["20.11"],
    "python": ["3.11"],
    "swift": ["5.9"]
  },
  "build_tools": ["fastlane", "cocoapods", "codesign"],
  "cpu": {
    "num_cpu": 10,
    "load_percent": 25.5
  },
  "disk": {
    "free_bytes": 54199226368,
    "used_percent": 77.89
  }
}
```

## Configuration Reference

### Runner Section

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `capacity` | int | 1 | Maximum concurrent jobs |
| `timeout` | duration | 3h | Maximum job execution time |
| `shutdown_timeout` | duration | 3m | Grace period for jobs to complete on shutdown |
| `insecure` | bool | false | Allow insecure HTTPS |
| `fetch_timeout` | duration | 5s | Timeout for fetching tasks |
| `fetch_interval` | duration | 2s | Interval between task fetches |
| `labels` | []string | [] | Runner labels for job matching |
| `env_file` | string | .env | Environment variables file |

### Cache Section

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | bool | true | Enable cache support |
| `dir` | string | "" | Cache directory path |
| `host` | string | "" | External cache server host |
| `port` | int | 0 | External cache server port |

### Container Section

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `network` | string | "" | Docker network for containers |
| `privileged` | bool | false | Run containers in privileged mode |
| `docker_host` | string | "" | Custom Docker host |
| `force_pull` | bool | false | Always pull latest images |

## Troubleshooting

### Capacity Not Being Applied

**Problem:** Runner shows `"capacity":1` even though config.yaml has `capacity: 2`

**Solution:** Ensure you're using the `-c` flag when starting the daemon:

```bash
# ✅ Correct
./gitcaddy-runner daemon -c /path/to/config.yaml

# ❌ Wrong - uses defaults
./gitcaddy-runner daemon
```

Verify the config is being loaded:
```bash
# Check runner process
ps aux | grep gitcaddy-runner

# Should show: gitcaddy-runner daemon -c /path/to/config.yaml
```

### Docker Not Detected

**Problem:** Capabilities show `"docker":false` but Docker is installed

**Solution:**
1. Ensure Docker Desktop/daemon is running:
   ```bash
   docker ps
   ```

2. Restart the runner after starting Docker:
   ```bash
   ./gitcaddy-runner daemon -c config.yaml
   ```

3. Check Docker socket permissions:
   ```bash
   ls -l /var/run/docker.sock
   ```

### Jobs Not Running Concurrently

**Problem:** Jobs queue instead of running in parallel

**Checklist:**
1. Verify capacity in capabilities output (check runner logs)
2. Confirm config.yaml has `capacity > 1`
3. Ensure runner was started with `-c config.yaml` flag
4. Check system resources aren't maxed out
5. Restart runner after config changes

### Runner Not Starting

**Problem:** Runner exits immediately or fails to start

**Common causes:**
1. Invalid config.yaml syntax
2. `.runner` file missing (run `register` first)
3. Permission issues on working directory
4. Invalid Gitea instance URL or token

**Debug steps:**
```bash
# Check config syntax
./gitcaddy-runner generate-config > test-config.yaml
diff config.yaml test-config.yaml

# Test with verbose logging
./gitcaddy-runner daemon -c config.yaml --log-level debug

# Verify registration
cat .runner
```

## Environment Variables

GitCaddy Runner supports environment variable configuration:

| Variable | Description | Example |
|----------|-------------|---------|
| `GITEA_RUNNER_CAPACITY` | Override capacity setting | `GITEA_RUNNER_CAPACITY=2` |
| `GITEA_RUNNER_ENV_FILE` | Custom env file path | `GITEA_RUNNER_ENV_FILE=.env.prod` |

## API Integration

Query runner capabilities via Gitea API:

```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://your-gitea.com/api/v1/runners
```

Use capabilities to generate compatible workflows:

```yaml
# Example: Use capabilities to select appropriate runner
name: Build
on: [push]
jobs:
  build:
    runs-on: ${{ capabilities.os == 'darwin' && 'macos-latest' || 'ubuntu-latest' }}
    steps:
      - uses: actions/checkout@v3
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- Issues: https://git.marketally.com/gitcaddy/gitcaddy-runner/issues
- Discussions: https://git.marketally.com/gitcaddy/gitcaddy-runner/discussions

## Acknowledgments

GitCaddy Runner is a hard fork of [Gitea's act_runner](https://gitea.com/gitea/act_runner), rebranded and enhanced with automated capability detection and reporting features for AI-friendly workflow generation.