gitea/README.md

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