Limited

Files

logikonline 1c0c1b8b74 docs(detached-note): expand README with comprehensive feature documentation

Add detailed table of contents and expand feature sections to cover all GitCaddy capabilities including core repository management, collaboration tools, CI/CD, package registry, vault system, AI features, and landing pages.

Reorganize content for better discoverability and add 600+ lines of documentation covering installation, configuration, usage examples, and API references.

Also update vault fix note with related projects table.

2026-01-27 22:17:47 -05:00

29 KiB

Raw Blame History

GitCaddy

The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-assisted development.

What is GitCaddy?
Key Features
Installation
Configuration
Usage
GitCaddy Runner
API Documentation
Internationalization
Building from Source
Contributing
License
Acknowledgments

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
Comprehensive Platform - Full-featured Git hosting with collaboration, CI/CD, package registry, and enterprise features

Key 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

Core Repository Management

Repository Operations: Create, fork, mirror (push/pull), and migrate repositories from external services
Branch & Tag Management: Branch protection rules with status checks, approval requirements, and reorderable protection rules
Code Browsing: Commit history, blame view, diff visualization, and file tree navigation with Vue-based sidebar
File Operations: Web-based editor for uploading, editing, and deleting files
Code Search: Full-text search across repository files
Release Management: Create releases with automatic release notes generation and archive old releases
Wiki Pages: Markdown-based documentation with full editing capabilities
Git LFS Support: Large File Storage for binary assets

Collaboration Tools

Issues: Labels, milestones, assignments, dependencies, and time tracking with real-time stopwatch
Pull Requests: Code review workflows with approval requirements and multiple merge strategies
Project Boards: Kanban-style boards with drag-and-drop organization using Sortable.js
Comments & Reactions: Mention autocomplete with Tribute.js, emoji reactions, and threaded discussions
Notifications: Comprehensive notification system for repository activity
Activity Tracking: Contribution graphs and activity heatmaps

CI/CD & Actions

Workflow Execution: Run GitHub Actions-compatible workflows with monitoring and logs
Runner Management: Track bandwidth, disk usage, and online/offline status
Job Queue: Monitor job status and view detailed execution logs
Secrets & Variables: Encrypted secrets management with CI/CD integration
Status Checks: Integrate workflow results into branch protection rules

Package Registry

Multi-format package hosting with versioning and dependency management:

Supported Formats: Alpine, Arch, Cargo, Chef, Composer, Conda, Debian, Docker, Go, Helm, Maven, npm, NuGet, PyPI, RPM, RubyGems, Swift, Vagrant
Access Controls: Global and per-package permission management
Version Management: Full version history and dependency tracking

Vault System (Pro/Enterprise)

Enterprise-grade encrypted secrets management:

Encrypted Storage: Version history for all secrets with rollback capabilities
Audit Logging: Comprehensive access logs with extended retention for Enterprise tier
CI/CD Integration: Generate tokens for workflow access to secrets
Tiered Licensing: Solo, Pro, Team, and Enterprise tiers with different feature sets

AI-Powered Features

AI Code Review: Automated code review suggestions on pull requests
Issue Triage: Automatic categorization and priority assignment
Code Explanation: Generate documentation and explain complex code
Error Diagnosis: AI learning patterns for debugging assistance

Landing Pages & Public Releases

Customizable repository landing pages with optional public access for private repositories:

Custom Domains: Configure custom domains with SSL management
Templates: Choose from pre-built templates or create custom designs
Branding: Logos, icons, and theme customization
Public Access: Expose landing pages and releases for private repos (perfect for commercial software with public downloads)

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 with 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()

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

Security & Authentication

Two-Factor Authentication: TOTP-based 2FA with recovery codes
WebAuthn/Hardware Keys: Passkey support with credential management
SSH/GPG Keys: Key management with parsing and validation
OAuth2/OpenID Connect: Integration with external identity providers
LDAP/SAML/SSPI: Enterprise authentication support
Signed Commits: GPG signature verification
Branch Protection: Enforce status checks and approval requirements

Organization Management

Team Management: Granular permissions with role-based access control
Member Roles: Owner, member, and restricted user types
Visibility Controls: Public, private, and limited organization visibility
Pinned Repositories: Feature important projects on organization pages
License Management: Organization-level licensing for Pro/Enterprise features

Advanced UI Features

Real-time Updates: EventSource/SharedWorker for synchronized time tracking across tabs
Interactive Tables: Sortable columns and filterable data
Math Rendering: LaTeX equations with KaTeX
Diagram Rendering: Mermaid diagrams in isolated iframes
Code Block Enhancements: Copy-to-clipboard buttons and syntax highlighting
Task Lists: Interactive checkboxes in Markdown
Terminal Playback: Asciinema recording playback
Accessibility: ARIA attributes, keyboard navigation, and screen reader support
Responsive Design: Mobile-friendly interface with overflow menus
Toast Notifications: Non-intrusive status messages with Toastify.js
Tooltips: Context-sensitive help with Tippy.js
Image Gallery: Project showcase capabilities

Installation

From Binary

Download from Releases:

# Linux (amd64)
curl -L -o gitcaddy-server https://git.marketally.com/gitcaddy/gitcaddy-server/releases/latest/download/gitcaddy-server-linux-amd64
chmod +x gitcaddy-server
./gitcaddy-server web

# macOS (arm64)
curl -L -o gitcaddy-server https://git.marketally.com/gitcaddy/gitcaddy-server/releases/latest/download/gitcaddy-server-darwin-arm64
chmod +x gitcaddy-server
./gitcaddy-server web

# Windows (amd64)
# Download gitcaddy-server-windows-amd64.exe and run:
gitcaddy-server.exe web

The server will start on http://localhost:3000 by default. On first run, you'll be redirected to the installation wizard.

From Source

# Clone the repository
git clone https://git.marketally.com/gitcaddy/gitcaddy-server.git
cd gitcaddy-server

# Build with SQLite support
TAGS="bindata sqlite sqlite_unlock_notify" make build

# Run the server
./gitcaddy-server web

Requirements:

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

Docker

# Run with Docker
docker run -d \
  --name gitcaddy \
  -p 3000:3000 \
  -v ./data:/data \
  gitcaddy/gitea:latest

# Or use Docker Compose
version: "3"
services:
  gitcaddy:
    image: gitcaddy/gitea:latest
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    restart: unless-stopped

Configuration

Database Setup

GitCaddy supports multiple database backends. Configure during installation or in app.ini:

Supported Databases:

SQLite (default, no additional setup required)
MySQL 5.7+ / MariaDB 10.2+
PostgreSQL 10+
MSSQL 2008+

Example MySQL Configuration:

[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gitcaddy
USER = gitcaddy
PASSWD = your_password

Example PostgreSQL Configuration:

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gitcaddy
USER = gitcaddy
PASSWD = your_password
SSL_MODE = disable

AI Features Configuration

Enable and configure AI-powered features in app.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

Authentication Sources

Configure external authentication through the admin dashboard or app.ini:

OAuth2 Providers:

GitHub, GitLab, Gitea, Bitbucket
Google, Microsoft, Discord, Twitter
Generic OAuth2 providers

LDAP/Active Directory:

[auth.ldap]
ENABLED = true
HOST = ldap.example.com
PORT = 389
BIND_DN = cn=admin,dc=example,dc=com
BIND_PASSWORD = password
USER_BASE = ou=users,dc=example,dc=com
USER_FILTER = (uid=%s)

SAML 2.0: Configure through the admin dashboard with your identity provider's metadata.

Email/SMTP Setup

Configure email notifications in app.ini:

[mailer]
ENABLED = true
FROM = noreply@your-instance.com
PROTOCOL = smtp
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 587
USER = your-email@gmail.com
PASSWD = your-app-password

Usage

Repository Operations

Creating Repositories:

Click the "+" icon in the top navigation
Select "New Repository"
Choose a template (optional) or start from scratch
Configure repository settings (visibility, README, .gitignore, license)

Forking:

Navigate to any repository
Click "Fork" in the top-right corner
Select the destination organization or user

Mirroring:

Create a new repository
Enable "This repository is a mirror"
Configure pull/push mirror settings
Set synchronization schedule

Migration:

Click "+" → "New Migration"
Select source platform (GitHub, GitLab, Gitea, Gogs)
Provide repository URL and credentials
Choose items to migrate (issues, PRs, releases, wiki)

Project Management

Issues:

Create issues with labels, milestones, and assignments
Add dependencies between issues
Track time with the built-in stopwatch (synchronized across browser tabs)
Use mentions (@username) with autocomplete
Add reactions and threaded comments

Pull Requests:

Create PRs from branches or forks
Request reviews from team members
View inline diff with syntax highlighting
Approve/request changes with review comments
Merge with strategies: merge commit, squash, or rebase

Project Boards:

Create Kanban boards with custom columns
Drag and drop issues/PRs between columns
Filter by labels, milestones, or assignees
Track progress with visual indicators

CI/CD Workflows

Creating Workflows:

Create .gitea/workflows/build.yml:

name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npm test

Validating Before Commit:

# Use the validation API
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/actions/workflows/validate \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "..."}'

Monitoring Workflows:

View workflow runs in the "Actions" tab
Check runner status and capabilities
View job logs in real-time
Re-run failed jobs

Package Registry Usage

Publishing npm Packages:

# Configure registry
npm config set registry https://your-instance.com/api/packages/owner/npm/

# Authenticate
npm login --registry=https://your-instance.com/api/packages/owner/npm/

# Publish
npm publish

Publishing Docker Images:

# Login
docker login your-instance.com

# Tag and push
docker tag myimage:latest your-instance.com/owner/myimage:latest
docker push your-instance.com/owner/myimage:latest

Other Formats: Refer to the package registry documentation for Maven, PyPI, Cargo, Helm, and other formats.

Vault Usage (Pro/Enterprise)

Creating Secrets:

Navigate to repository settings → Vault
Click "New Secret"
Enter key-value pairs
Secrets are automatically encrypted and versioned

Using in Workflows:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: ./deploy.sh

Viewing Audit Logs:

Access audit logs in the Vault section
Filter by user, action, and date range
Export logs for compliance (Enterprise tier)

Rolling Back Secrets:

View secret history
Select a previous version
Click "Restore"

Landing Pages Configuration

Creating a Landing Page:

Create .gitea/landing.yaml in your repository:

enabled: true
public_landing: true  # For private repos with public landing page

hero:
  title: "My Amazing Project"
  tagline: "The best solution for your needs"
  cta_text: "Download Now"
  cta_link: "/releases/latest"

features:
  - title: "Fast"
    description: "Lightning-fast performance"
    icon: "⚡"
  - title: "Secure"
    description: "Enterprise-grade security"
    icon: "🔒"

gallery:
  - image: "screenshot1.png"
    caption: "Main interface"
  - image: "screenshot2.png"
    caption: "Advanced features"

advanced:
  custom_domain: "myproject.com"
  ssl_enabled: true
  public_releases: true

Commit and push the file
Access your landing page at https://your-instance.com/owner/repo/pages

AI Features Usage

AI Code Review:

Create a pull request
Enable AI review in PR settings
AI will analyze changes and provide suggestions
Review and apply suggestions as needed

Issue Triage:

AI automatically categorizes new issues
Suggests labels based on content
Estimates complexity
Recommends relevant files for investigation

Code Explanation:

Select code in the file viewer
Click "Explain with AI"
View generated documentation

Using AI Context APIs:

# Get repository summary
curl https://your-instance.com/api/v2/ai/repo/summary?owner=owner&repo=repo \
  -H "Authorization: token YOUR_TOKEN"

# Get issue context
curl https://your-instance.com/api/v2/ai/issue/context?owner=owner&repo=repo&issue=123 \
  -H "Authorization: token YOUR_TOKEN"

# Get repository navigation
curl https://your-instance.com/api/v2/ai/repo/navigation?owner=owner&repo=repo&depth=3 \
  -H "Authorization: token YOUR_TOKEN"

GitCaddy Runner

For full capability reporting and optimal workflow execution, 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 with your GitCaddy instance
./act_runner register \
  --instance https://your-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name my-runner \
  --labels ubuntu-latest,docker

# Run the runner daemon
./act_runner daemon

Automatic Capability Detection:

The runner automatically detects and reports:

Operating system and architecture
Docker/Podman availability and version
Docker Compose support
Installed tools and their versions:
- Node.js
- Go
- Python
- Java
- .NET
- Rust
- Ruby
- PHP
Available shells (bash, sh, pwsh, cmd)
Cache support
Service containers support

Viewing Runner Capabilities:

Access runner capabilities through the API or UI:

curl https://your-instance.com/api/v2/repos/owner/repo/actions/runners/capabilities \
  -H "Authorization: token YOUR_TOKEN"

API Documentation

GitCaddy provides comprehensive API documentation:

Interactive Explorer: Visit /api/v2/docs on your instance for the Scalar API explorer
OpenAPI Specification: Download from /api/v2/swagger.json
Legacy API: V1 API documentation available at /api/swagger

Authentication:

All API endpoints require authentication via token:

# Create a token in Settings → Applications → Generate New Token

# Use in requests
curl https://your-instance.com/api/v2/repos/owner/repo \
  -H "Authorization: token YOUR_TOKEN"

Common API Operations:

# List repositories
GET /api/v2/user/repos

# Get repository details
GET /api/v2/repos/{owner}/{repo}

# Create an issue
POST /api/v2/repos/{owner}/{repo}/issues

# List pull requests
GET /api/v2/repos/{owner}/{repo}/pulls

# Get runner capabilities
GET /api/v2/repos/{owner}/{repo}/actions/runners/capabilities

# Validate workflow
POST /api/v2/repos/{owner}/{repo}/actions/workflows/validate

# Batch file retrieval
GET /api/v2/batch/files?paths=file1.go,file2.go&owner=owner&repo=repo

# Stream files (NDJSON)
POST /api/v2/stream/files

Internationalization

GitCaddy supports 12+ languages with full UI translation:

Supported Languages:

German (de-DE)
English (en-US)
Irish (ga-IE)
Hindi (hi-IN)
Hungarian (hu-HU)
Indonesian (id-ID)
Icelandic (is-IS)
Italian (it-IT)
Dutch (nl-NL)
Polish (pl-PL)
Brazilian Portuguese (pt-BR)
Portuguese (pt-PT)

Changing Language:

Click your avatar in the top-right
Select "Settings"
Choose "Language" from the dropdown
Save changes

Contributing Translations:

Translations are stored in JSON files at options/locale/. To contribute:

Copy an existing locale file
Translate all strings
Submit a pull request

Building from Source