# GitCaddy The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-assisted development. ## What is GitCaddy? GitCaddy transforms Git hosting into an AI-ready platform. While traditional Git servers treat AI tools as an afterthought, GitCaddy is built from the ground up with structured APIs, capability discovery, and intelligent context that AI assistants need to write correct code, generate valid CI/CD workflows, and understand your projects deeply. **Key differentiators:** - **V2 API** - Modern, AI-optimized endpoints with batch operations, streaming, and structured errors - **Runner Capability Discovery** - AI tools query runner capabilities before generating workflows - **Action Compatibility Database** - Curated compatibility matrix prevents workflow errors - **AI Context APIs** - Rich, structured repository and issue intelligence - **Workflow Validation** - Pre-flight checks for CI/CD workflows before commit ## Features ### V2 API - Modern, AI-Optimized Interface A complete API redesign focused on AI tool consumption: | Feature | Description | |---------|-------------| | **Batch Operations** | Fetch up to 100 files in a single request | | **Streaming** | NDJSON streams for progressive processing | | **Idempotency** | Built-in support for safe request retries | | **Structured Errors** | Machine-readable error codes, not just HTTP status | | **Request Tracking** | Every request gets a unique ID for debugging | | **Health Checks** | Kubernetes-compatible liveness/readiness probes | | **Operation Progress** | Server-Sent Events for long-running operations | ``` GET /api/v2/batch/files # Bulk file retrieval POST /api/v2/stream/files # NDJSON streaming GET /api/v2/operations/{id} # Operation status GET /api/v2/health/ready # Readiness probe ``` ### AI Context APIs - Repository Intelligence Purpose-built endpoints that give AI tools the context they need: **Repository Summary** (`/api/v2/ai/repo/summary`) ```json { "name": "my-project", "primary_language": "Go", "project_type": "application", "build_system": "go modules", "test_framework": "go test", "suggested_entry_points": ["cmd/main.go", "internal/app/"], "config_files": ["go.mod", "Makefile", ".gitea/workflows/"], "language_stats": {"Go": 45000, "YAML": 2000} } ``` **Repository Navigation** (`/api/v2/ai/repo/navigation`) - Directory tree with depth control - Important paths ranked by priority (entry points, tests, docs) - File type distribution **Issue Context** (`/api/v2/ai/issue/context`) - Issue details with all comments - Related issues and code references - AI hints: category (bug/feature), complexity estimation, suggested files ### Runner Capability Discovery Runners report their capabilities. AI tools query before generating workflows. **Endpoint:** `GET /api/v2/repos/{owner}/{repo}/actions/runners/capabilities` ```json { "runners": [ { "id": 1, "name": "ubuntu-runner", "status": "online", "labels": ["ubuntu-latest", "docker"], "capabilities": { "os": "linux", "arch": "amd64", "docker": true, "docker_compose": true, "shell": ["bash", "sh"], "tools": { "node": ["18.19.0", "20.10.0"], "go": ["1.21.5", "1.22.0"], "python": ["3.11.6", "3.12.0"] }, "features": { "cache": true, "services": true } } } ], "platform": { "type": "gitea", "version": "1.26.0", "supported_actions": { "actions/checkout": {"versions": ["v3", "v4"]}, "actions/setup-node": {"versions": ["v3", "v4"]}, "actions/upload-artifact": {"versions": ["v3"], "notes": "v4 not supported"} }, "unsupported_features": [ "GitHub-hosted runners", "OIDC token authentication" ] }, "workflow_hints": { "preferred_checkout": "actions/checkout@v4", "artifact_upload_alternative": "Use Gitea API for artifacts" } } ``` ### Workflow Validation Validate workflows before committing. Catch incompatibilities early. **Endpoint:** `POST /api/v2/repos/{owner}/{repo}/actions/workflows/validate` ```json // Request { "content": "name: Build\non: push\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/upload-artifact@v4" } // Response { "valid": false, "warnings": [ { "line": 8, "action": "actions/upload-artifact@v4", "severity": "error", "message": "actions/upload-artifact@v4 is not supported", "suggestion": "Use actions/upload-artifact@v3" } ], "runner_match": [ { "job": "build", "runs_on": ["ubuntu-latest"], "matched_runners": ["ubuntu-runner-1"], "capabilities_met": true } ] } ``` ### Action Compatibility Database Built-in knowledge of GitHub Action compatibility: | Action | Compatible Versions | Notes | |--------|-------------------|-------| | `actions/checkout` | v2, v3, v4 | Fully compatible | | `actions/setup-node` | v2, v3, v4 | Fully compatible | | `actions/setup-go` | v3, v4, v5 | Fully compatible | | `actions/setup-python` | v4, v5 | Fully compatible | | `actions/cache` | v3, v4 | Fully compatible | | `actions/upload-artifact` | v2, v3 | v4 not supported | | `actions/download-artifact` | v2, v3 | v4 not supported | ### Release Archive Archive old releases without deleting them: - Toggle archived status via UI or API - Filter releases by archived state - Archived releases hidden by default, toggle to show - Preserves release history for compliance ``` POST /api/v1/repos/{owner}/{repo}/releases/{id}/archive DELETE /api/v1/repos/{owner}/{repo}/releases/{id}/archive GET /api/v1/repos/{owner}/{repo}/releases?archived=false ``` ### Public Landing Pages & Releases for Private Repos Private repositories can expose a public landing page and/or public releases. Perfect for: - Commercial software with private source but public downloads - Open-core projects with public documentation - Electron/desktop apps needing public update endpoints Configure in `.gitea/landing.yaml`: ```yaml enabled: true public_landing: true # Allow unauthenticated access to landing page hero: title: "My App" tagline: "The best app ever" advanced: public_releases: true # Allow unauthenticated access to releases ``` **API Endpoints (no auth required when enabled):** ``` GET /api/v2/repos/{owner}/{repo}/pages/config # Landing page config GET /api/v2/repos/{owner}/{repo}/pages/content # Landing page content GET /api/v2/repos/{owner}/{repo}/releases # List releases GET /api/v2/repos/{owner}/{repo}/releases/latest # Latest release ``` ### App Update API (Electron/Squirrel Compatible) Purpose-built endpoint for desktop app auto-updates. Returns Squirrel-compatible JSON format. **Endpoint:** `GET /api/v2/repos/{owner}/{repo}/releases/update` **Query Parameters:** | Parameter | Description | Default | |-----------|-------------|---------| | `version` | Current app version (semver) | Required | | `platform` | `darwin`, `windows`, `linux` | Runtime OS | | `arch` | `x64`, `arm64` | Runtime arch | | `channel` | `stable`, `beta`, `alpha` | `stable` | **Response (200 OK - update available):** ```json { "url": "https://git.example.com/owner/repo/releases/download/v1.2.0/App-darwin-arm64.zip", "name": "v1.2.0", "notes": "Release notes in markdown...", "pub_date": "2026-01-10T12:00:00Z", "platform": { "size": 45000000, "releases_url": "https://...", // Windows RELEASES file "nupkg_url": "https://..." // Windows nupkg } } ``` **Response (204 No Content):** No update available **Electron Integration:** ```typescript // In your Electron app import { autoUpdater } from 'electron' const version = app.getVersion() const platform = process.platform const arch = process.arch === 'arm64' ? 'arm64' : 'x64' autoUpdater.setFeedURL({ url: `https://git.example.com/api/v2/repos/owner/repo/releases/update?version=${version}&platform=${platform}&arch=${arch}` }) autoUpdater.checkForUpdates() ``` ## Installation ### From Binary Download from [Releases](https://git.marketally.com/gitcaddy/gitea/releases): ```bash # Linux (amd64) curl -L -o gitcaddy https://git.marketally.com/gitcaddy/gitea/releases/latest/download/gitea-linux-amd64 chmod +x gitcaddy ./gitcaddy web ``` ### From Source ```bash git clone https://git.marketally.com/gitcaddy/gitea.git cd gitea TAGS="bindata sqlite sqlite_unlock_notify" make build ./gitea web ``` ### Docker ```bash docker run -d \ --name gitcaddy \ -p 3000:3000 \ -v ./data:/data \ gitcaddy/gitea:latest ``` ## Configuration GitCaddy uses the same configuration as Gitea. Key settings for AI features: ```ini [server] ROOT_URL = https://your-instance.com/ [actions] ENABLED = true [api] ; Enable V2 API (enabled by default) ENABLE_V2_API = true ; Max files in batch request MAX_BATCH_SIZE = 100 ; Enable AI context endpoints ENABLE_AI_CONTEXT = true ``` ## GitCaddy Runner For full capability reporting, use the [GitCaddy act_runner](https://git.marketally.com/gitcaddy/act_runner): ```bash # Download curl -L -o act_runner https://git.marketally.com/gitcaddy/act_runner/releases/latest/download/act_runner-linux-amd64 chmod +x act_runner # Register ./act_runner register \ --instance https://your-instance.com \ --token YOUR_TOKEN \ --name my-runner # Run (automatically detects and reports capabilities) ./act_runner daemon ``` The runner automatically detects: - OS and architecture - Docker/Podman availability - Installed tools (Node.js, Go, Python, Java, .NET, Rust) - Available shells - Docker Compose support ## API Documentation Interactive API documentation available at: - `/api/v2/docs` - Scalar API explorer - `/api/v2/swagger.json` - OpenAPI specification ## Architecture ``` GitCaddy | +------------------------------+------------------------------+ | | | V2 API Layer Actions Engine Web Interface | | | +----+----+ +----+----+ +----+----+ | | | | | | Batch Streaming Runners Workflows Repos Releases Files (NDJSON) Capability Validation (Archive) | | Discovery | | | | | +----+----+--------------------+---------+ | AI Context APIs | +----+----+----+ | | | | Repo Issue Nav Summary ``` ## Related Projects | Project | Description | |---------|-------------| | [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with capability detection | | [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol definitions | ## Building Requirements: - Go 1.24+ (see `go.mod`) - Node.js 22.6+ (for frontend) - Make ```bash # Full build TAGS="bindata sqlite sqlite_unlock_notify" make build # Backend only make backend # Frontend only make frontend # Run tests make test ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Run tests: `make test` 5. Submit a pull request ## License MIT License - see [LICENSE](LICENSE) for details. --- ## Acknowledgments GitCaddy is a fork of [Gitea](https://gitea.io), the open-source self-hosted Git service. We thank the Gitea team and all contributors for building the foundation that makes GitCaddy possible. - [Gitea Project](https://gitea.io) - [Gitea Contributors](https://github.com/go-gitea/gitea/graphs/contributors)