Add professional README for GitCaddy fork

Document capability detection, installation, configuration, and GitCaddy integration with architecture diagram. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 05:03:21 -05:00
parent aefab79307
commit c6b9e0c2d1
1 changed files with 154 additions and 67 deletions
--- a/README.md
+++ b/README.md
@@ -1,108 +1,195 @@
-# act runner
+# GitCaddy Act Runner

-Act runner is a runner for Gitea based on [Gitea fork](https://gitea.com/gitea/act) of [act](https://github.com/nektos/act).
+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

-### Prerequisites
+### Download Pre-built Binary

-Docker Engine Community version is required for docker mode. To install Docker CE, follow the official [install instructions](https://docs.docker.com/engine/install/).
-
-### Download pre-built binary
-
-Visit [here](https://dl.gitea.com/act_runner/) and download the right version for your platform.
-
-### Build from source
+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
 ```

-### Build a docker image
+## Quick Start

-```bash
-make docker
-```
+### 1. Enable Actions in Gitea

-## Quickstart
-
-Actions are disabled by default, so you need to add the following to the configuration file of your Gitea instance to enable it: 
+Add to your Gitea `app.ini`:

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

-### Register
+### 2. Register the Runner

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

-And you will be asked to input:
-
-1. Gitea instance URL, like `http://192.168.8.8:3000/`. You should use your gitea instance ROOT_URL as the instance argument
- and you should not use `localhost` or `127.0.0.1` as instance IP;
-2. Runner token, you can get it from `http://192.168.8.8:3000/admin/actions/runners`;
-3. Runner name, you can just leave it blank;
-4. Runner labels, you can just leave it blank.
-
-The process looks like:
-
-```text
-INFO Registering runner, arch=amd64, os=darwin, version=0.1.5.
-WARN Runner in user-mode.
-INFO Enter the Gitea instance URL (for example, https://gitea.com/):
-http://192.168.8.8:3000/
-INFO Enter the runner token:
-fe884e8027dc292970d4e0303fe82b14xxxxxxxx
-INFO Enter the runner name (if set empty, use hostname: Test.local):
-
-INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest):
-
-INFO Registering runner, name=Test.local, instance=http://192.168.8.8:3000/, labels=[ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04 ubuntu-20.04:docker://docker.gitea.com/runner-images:ubuntu-20.04].
-DEBU Successfully pinged the Gitea instance server
-INFO Runner registered successfully.
-```
-
-You can also register with command line arguments.
-
-```bash
-./act_runner register --instance http://192.168.8.8:3000 --token <my_runner_token> --no-interactive
-```
-
-If the registry succeed, it will run immediately. Next time, you could run the runner directly.
-
-### Run
+### 3. Start the Runner

 ```bash
 ./act_runner daemon
 ```

-### Run with docker
+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

-```bash
-docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/act_runner:nightly
+## 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
+## Configuration

-You can also configure the runner with a configuration file.
-The configuration file is a YAML file, you can generate a sample configuration file with `./act_runner generate-config`.
+Create a config file or use command-line flags:

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

-You can specify the configuration file path with `-c`/`--config` argument.
+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
-./act_runner -c config.yaml register # register with config file
-./act_runner -c config.yaml daemon # run with config file
+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
 ```

-You can read the latest version of the configuration file online at [config.example.yaml](internal/pkg/config/config.example.yaml).
+## GitCaddy Integration

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

-Check out the [examples](examples) directory for sample deployment types.
+- **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.