gitcaddy-server/README.md

GitCaddy

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

Table of Contents

• What is GitCaddy?
• Key Features
  • V2 API - Modern, AI-Optimized Interface
  • AI Context APIs - Repository Intelligence
  • Runner Capability Discovery
  • Workflow Validation
  • Action Compatibility Database
  • Core Repository Management
  • Collaboration Tools
  • CI/CD & Actions
  • Package Registry
  • Vault System (Pro/Enterprise)
  • AI-Powered Features
  • Landing Pages & Public Releases
  • App Update API (Electron/Squirrel Compatible)
  • Release Archive
  • Security & Authentication
  • Organization Management
  • Advanced UI Features
• Installation
  • From Binary
  • From Source
  • Docker
• Configuration
  • Database Setup
  • AI Features Configuration
  • Authentication Sources
  • Email/SMTP Setup
  • Unsplash Integration
• Usage
  • Repository Operations
  • Project Management
  • CI/CD Workflows
  • Package Registry Usage
  • Vault Usage (Pro/Enterprise)
  • Landing Pages Configuration
  • AI Features 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

Unsplash Integration

Enable Unsplash image search for repository social card backgrounds (Media Kit). This allows repository admins to search and select high-quality background images directly from Unsplash.

[unsplash]
; Enable Unsplash integration for Media Kit background images
ENABLED = true
; Unsplash API access key (get one at https://unsplash.com/developers)
ACCESS_KEY = your_unsplash_access_key

To obtain an access key:

1. Create an account at unsplash.com/developers
2. Create a new application
3. Copy the Access Key (the Secret Key is not needed)

When enabled, repository admins can search Unsplash from Settings > Media Kit when using the "Background Image" social card style. Attribution is handled automatically per Unsplash API guidelines.

Usage

Repository Operations

Creating Repositories:

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

Forking:

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

Mirroring:

1. Create a new repository
2. Enable "This repository is a mirror"
3. Configure pull/push mirror settings
4. Set synchronization schedule

Migration:

1. Click "+" → "New Migration"
2. Select source platform (GitHub, GitLab, Gitea, Gogs)
3. Provide repository URL and credentials
4. 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:

1. Navigate to repository settings → Vault
2. Click "New Secret"
3. Enter key-value pairs
4. 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:

1. View secret history
2. Select a previous version
3. Click "Restore"

Landing Pages Configuration

Creating a Landing Page:

1. 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

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

AI Features Usage

AI Code Review:

1. Create a pull request
2. Enable AI review in PR settings
3. AI will analyze changes and provide suggestions
4. 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:

1. Select code in the file viewer
2. Click "Explain with AI"
3. 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:

1. Click your avatar in the top-right
2. Select "Settings"
3. Choose "Language" from the dropdown
4. Save changes

Contributing Translations:

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

1. Copy an existing locale file
2. Translate all strings
3. Submit a pull request

Building from Source

Requirements:

• Go 1.24+ (see go.mod for exact version)
• Node.js 22.6+
• Make
• Git

Build Commands:

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

# Full build (backend + frontend)
TAGS="bindata sqlite sqlite_unlock_notify" make build

# Backend only
make backend

# Frontend only
make frontend

# Run tests
make test

# Run with live reload (development)
make watch

# Generate API documentation
make generate-swagger

Build Tags:

• bindata - Embed static assets into binary
• sqlite - Enable SQLite support
• sqlite_unlock_notify - Enable SQLite unlock notifications
• pam - Enable PAM authentication
• gogit - Use pure Go git implementation

Development Setup:

# Install frontend dependencies
npm install

# Run frontend in development mode
npm run dev

# Run backend with hot reload
make watch-backend

# Run tests with coverage
make test-coverage

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository on GitCaddy
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes with clear commit messages
4. Run tests: make test
5. Run linters: make lint
6. Submit a pull request with a clear description

Code Style:

• Go: Follow standard Go conventions (gofmt, golint)
• TypeScript: Use ESLint configuration in the repository
• Commit messages: Use conventional commits format

Testing:

• Write unit tests for new features
• Ensure all tests pass before submitting
• Add integration tests for API changes

Documentation:

• Update README.md for user-facing changes
• Add API documentation for new endpoints
• Include code comments for complex logic

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 - The upstream project
• Claude Code - AI-assisted development by Anthropic
• Gitea Contributors - All the amazing contributors

---

Related Projects:

Project	Description
gitcaddy/act_runner	Runner with automatic capability detection
gitcaddy/actions-proto-go	Protocol buffer definitions for Actions

Support:

• Documentation: https://docs.gitcaddy.com
• Issues: Report bugs and request features on our issue tracker
• Community: Join discussions in our repository