act_runner/README.md

# GitCaddy Act Runner

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

> **This is a GitCaddy fork** of [gitea.com/gitea/act_runner](https://gitea.com/gitea/act_runner) with runner capability discovery features.

## Overview

Act Runner executes Gitea Actions workflows using [act](https://github.com/nektos/act). This fork adds automatic capability detection, enabling Gitea to expose runner capabilities via API for AI tools to query before generating workflows.

## Key Features

- **Capability Detection**: Automatically detects OS, architecture, Docker support, available shells, and installed tools
- **Capability Reporting**: Reports capabilities to Gitea server during runner declaration
- **Full Compatibility**: Drop-in replacement for standard act_runner
- **Multi-Platform**: Supports Linux, macOS, and Windows

## Installation

### Download Pre-built Binary

Download from [Releases](https://git.marketally.com/gitcaddy/act_runner/releases):

```bash
# Linux (amd64)
curl -L -o act_runner https://git.marketally.com/gitcaddy/act_runner/releases/download/v0.3.1-gitcaddy/act_runner-linux-amd64
chmod +x act_runner

# macOS (Apple Silicon)
curl -L -o act_runner https://git.marketally.com/gitcaddy/act_runner/releases/download/v0.3.1-gitcaddy/act_runner-darwin-arm64
chmod +x act_runner
```

### Build from Source

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

## Quick Start

### 1. Enable Actions in Gitea

Add to your Gitea `app.ini`:

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

### 2. Register the Runner

```bash
./act_runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_RUNNER_TOKEN \
  --name my-runner \
  --labels ubuntu-latest,docker
```

### 3. Start the Runner

```bash
./act_runner daemon
```

On startup, the runner will:
1. Detect system capabilities (OS, arch, Docker, shells, tools)
2. Report capabilities to Gitea via the Declare API
3. Begin polling for jobs

## Capability Detection

The runner automatically detects:

| Category | Examples |
|----------|----------|
| **OS/Arch** | linux/amd64, darwin/arm64, windows/amd64 |
| **Container Runtime** | Docker, Podman |
| **Shells** | bash, sh, zsh, powershell, cmd |
| **Tools** | Node.js, Go, Python, Java, .NET, Rust |
| **Features** | Cache support, Docker Compose |

### Example Capabilities JSON

```json
{
  "os": "linux",
  "arch": "amd64",
  "docker": true,
  "docker_compose": true,
  "container_runtime": "docker",
  "shell": ["bash", "sh"],
  "tools": {
    "node": ["18.19.0"],
    "go": ["1.21.5"],
    "python": ["3.11.6"]
  },
  "features": {
    "cache": true,
    "docker_services": true
  },
  "limitations": []
}
```

## Configuration

Create a config file or use command-line flags:

```bash
./act_runner generate-config > config.yaml
./act_runner -c config.yaml daemon
```

Example configuration:

```yaml
log:
  level: info

runner:
  file: .runner
  capacity: 1
  timeout: 3h
  labels:
    - ubuntu-latest:docker://node:18-bullseye
    - ubuntu-22.04:docker://ubuntu:22.04

container:
  docker_host: ""
  force_pull: false
  privileged: false

cache:
  enabled: true
  dir: ~/.cache/actcache
```

## Docker Deployment

```bash
docker run -d \
  --name act_runner \
  -e GITEA_INSTANCE_URL=https://your-gitea.com \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/data \
  gitcaddy/act_runner:latest
```

## GitCaddy Integration

This runner is designed to work with the [GitCaddy Gitea fork](https://git.marketally.com/gitcaddy/gitea), which provides:

- **Runner Capabilities API** (`/api/v2/repos/{owner}/{repo}/actions/runners/capabilities`)
- **Workflow Validation API** for pre-flight checks
- **Action Compatibility Database** for GitHub Actions mapping

### How It Works

```

  act_runner                      Gitea                    AI Tool
      |                             |                         |
      |  Declare + Capabilities     |                         |
      |---------------------------->|                         |
      |                             |                         |
      |                             |  GET /api/v2/.../caps   |
      |                             |<------------------------|
      |                             |                         |
      |                             |  Runner capabilities    |
      |                             |------------------------>|
      |                             |                         |
      |                             |     Generates workflow  |
      |                             |     with correct config |

```

## Related Projects

| Project | Description |
|---------|-------------|
| [gitcaddy/gitea](https://git.marketally.com/gitcaddy/gitea) | Gitea with AI-friendly enhancements |
| [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol definitions with capability support |

## Upstream

This project is a fork of [gitea.com/gitea/act_runner](https://gitea.com/gitea/act_runner). We contribute enhancements back to upstream where appropriate.

## License

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