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)

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

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

// 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:

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):

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

// 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:

# 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

git clone https://git.marketally.com/gitcaddy/gitea.git
cd gitea
TAGS="bindata sqlite sqlite_unlock_notify" make build
./gitea web

Docker

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:

[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:

# 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	Runner with capability detection
gitcaddy/actions-proto-go	Protocol definitions

Building

Requirements:

• Go 1.24+ (see go.mod)
• Node.js 22.6+ (for frontend)
• Make

# 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 for details.

---

Acknowledgments

GitCaddy is a fork of Gitea, 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
• Gitea Contributors