diff --git a/README.md b/README.md index 9a5f566..0195020 100644 --- 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 +Add to your Gitea `app.ini`: -Actions are disabled by default, so you need to add the following to the configuration file of your Gitea instance to enable it: - ```ini [actions] -ENABLED=true +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 --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= -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= \ + -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.