CI / build-and-test (push) Waiting to run

Details

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

5.1 KiB

Raw Permalink Blame History

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 with runner capability discovery features.

Overview

Act Runner executes Gitea Actions workflows using 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:

# 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

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:

[actions]
ENABLED = true

2. Register the Runner

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

3. Start the Runner

./act_runner daemon

On startup, the runner will:

Detect system capabilities (OS, arch, Docker, shells, tools)
Report capabilities to Gitea via the Declare API
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

{
  "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:

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

Example configuration:

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

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, 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 |

Project	Description
gitcaddy/gitea	Gitea with AI-friendly enhancements
gitcaddy/actions-proto-go	Protocol definitions with capability support

Upstream

This project is a fork of gitea.com/gitea/act_runner. We contribute enhancements back to upstream where appropriate.

License

MIT License - see LICENSE for details.

5.1 KiB Raw Permalink Blame History