gitcaddy/GitCaddy Server
Limited
2
0
Fork 0
Code Issues Releases 14
Files
e932582f5416a3aa8fb1fa0fc1c5bc28b6581561
gitcaddy-server/README.md
logikonline e932582f54 docs(plugins): add comprehensive plugin development guide 
Add PLUGINS.md with complete documentation for building external GitCaddy plugins using the gRPC-based plugin protocol.

Documentation includes:
- Protocol overview and service definition
- Lifecycle diagram (Initialize → HealthCheck → OnEvent/HandleHTTP → Shutdown)
- Complete message reference for all 6 RPC methods
- Plugin manifest specification (routes, events, permissions, license tiers)
- Health monitoring and auto-restart behavior
- Configuration guide for external vs managed mode
- Transport details (h2c/HTTP2, gRPC wire format)
- Full working examples in Go, C#, and Python
- Debugging tips and common issues

Also updates README.md to reference the plugin guide and removes outdated Chinese translations (zh-cn, zh-tw) that were not being maintained.

This provides plugin developers with everything needed to build and deploy external services that integrate with GitCaddy's plugin framework.
2026-02-13 01:54:25 -05:00

43 KiB
Raw Blame History

GitCaddy

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

Table of Contents

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

GitCaddy integrates with the gitcaddy-ai sidecar service to provide two tiers of AI operations:

Tier 1 - Light Operations (seconds, via gRPC/REST to gitcaddy-ai):

  • AI Code Review: Automatic review comments on pull requests when opened or updated
  • Issue Auto-Respond: AI generates helpful responses to new issues and @bot mentions
  • Issue Triage: Automatic label assignment based on issue content
  • Code Explanation: On-demand explanation of code sections
  • Documentation Generation: Generate docs for code files

Tier 2 - Agent Operations (minutes, via Actions runners with Claude Code):

  • Agent Fix: AI agent clones the repo, investigates issues, creates branches and pull requests
  • Triggered by labels (e.g., adding ai-fix label) or manual API call
  • Sandboxed in existing Actions runner infrastructure

Configuration Cascade: Settings resolve from most specific to least: Repo > Org > System. Each level can override the AI provider, model, and API key.

Built-in Safety:

  • Dedicated bot user (gitcaddy-ai) for clear attribution
  • Loop prevention: bot-created events never re-trigger AI
  • Per-repo rate limiting (ops/hour)
  • Admin feature gates for every operation type
  • Escalation to staff when AI confidence is low or operations fail
  • Full audit log of every AI operation with provider, tokens, duration, and status

Plugin Framework

Extend GitCaddy with external plugins that communicate over gRPC (HTTP/2). The server manages plugin lifecycle, health monitoring, and event dispatch.

  • gRPC Protocol: Type-safe plugin contract defined in plugin.proto with 6 RPCs (Initialize, Shutdown, HealthCheck, GetManifest, OnEvent, HandleHTTP)
  • Health Monitoring: Automatic periodic health checks with configurable interval; plugins marked offline after 3 consecutive failures
  • Auto-Restart: Managed plugins are automatically restarted when they become unresponsive
  • Event Dispatch: Plugins subscribe to server events (e.g., license:updated) and receive them in real-time
  • Route Declaration: Plugins declare REST routes in their manifest; the server can proxy HTTP requests to the plugin
  • Managed & External Modes: Server can launch and manage plugin processes, or connect to already-running services

See PLUGINS.md for the full plugin development guide.

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

AI features require the gitcaddy-ai sidecar service running alongside your GitCaddy instance. See the gitcaddy-ai README for deployment instructions (Docker Compose recommended).

1. Enable AI in app.ini:

[ai]
; Master switch — nothing AI-related runs unless this is true
ENABLED = true

; gitcaddy-ai sidecar address (REST port)
SERVICE_URL = localhost:5050
SERVICE_TOKEN =

; Connection settings
TIMEOUT = 30s
MAX_RETRIES = 3

; Default provider/model (fallback when org/repo don't override)
DEFAULT_PROVIDER = claude          ; claude, openai, or gemini
DEFAULT_MODEL = claude-sonnet-4-20250514

; System API keys (used when org/repo don't provide their own)
CLAUDE_API_KEY = sk-ant-...
OPENAI_API_KEY =
GEMINI_API_KEY =

; Rate limiting (per repo)
MAX_OPERATIONS_PER_HOUR = 100
MAX_TOKENS_PER_OPERATION = 8192

; Feature gates — admin controls what's available instance-wide
ENABLE_CODE_REVIEW = true          ; Tier 1: PR review
ENABLE_ISSUE_TRIAGE = true         ; Tier 1: auto-label issues
ENABLE_DOC_GEN = true              ; Tier 1: documentation generation
ENABLE_EXPLAIN_CODE = true         ; Tier 1: code explanation
ENABLE_CHAT = true                 ; Tier 1: chat interface
ALLOW_AUTO_RESPOND = true          ; Tier 1: auto-respond to issues
ALLOW_AUTO_REVIEW = true           ; Tier 1: auto-review PRs
ALLOW_AGENT_MODE = false           ; Tier 2: agent fix (off by default, requires runner setup)

; Content limits
MAX_FILE_SIZE_KB = 500
MAX_DIFF_LINES = 5000

; Bot user (created automatically on first startup)
BOT_USER_NAME = gitcaddy-ai

2. Configure org-level settings (optional):

Organization admins can override the provider, model, and API key for all repos in the org. This is done via:

  • Web UI: /{org}/settings/ai
  • API: PUT /api/v2/orgs/{org}/ai/settings

Org settings include:

  • Provider & model selection
  • API key (encrypted at rest)
  • Rate limits (max ops/hour)
  • Allowed operations list
  • Agent mode toggle

3. Enable AI on a repository:

Repository admins enable AI and choose which operations to activate. This is done via:

  • Web UI: /{owner}/{repo}/settings/ai
  • API: PUT /api/v2/repos/{owner}/{repo}/ai/settings

Repo settings include:

  • Enable/Disable: Toggles the AI unit on the repo
  • Tier 1 Operations: Auto-respond to issues, auto-review PRs, auto-triage issues, auto-inspect workflows
  • Tier 2 Agent Mode: Enable agent fix, configure trigger labels (e.g., ai-fix), set max run time
  • Escalation: Enable staff escalation on failure, set escalation label and team
  • Provider Override: Override org/system provider and model for this repo
  • Custom Instructions: System instructions, review instructions, issue response instructions

4. Set up Tier 2 agent runners (optional):

For agent mode (AI that creates branches and PRs), you need an Actions runner with Claude Code installed:

  1. Register a runner with the ai-runner label
  2. Install the Claude Code CLI on the runner
  3. Place the agent workflow file in your repo at .gitea/workflows/ai-agent.yml (a template is available via the API)
  4. Set the AI_API_KEY secret on the repo or org

When a trigger label is added to an issue (or an agent fix is requested via API), the server dispatches the workflow, the runner clones the repo, runs Claude Code headless, and creates a PR with the proposed fix.

Plugin Framework Configuration

The plugin framework allows external services (like the AI sidecar) to register with GitCaddy for lifecycle management, health monitoring, and event dispatch. Plugins communicate over gRPC (HTTP/2) using the protocol defined in modules/plugins/pluginv1/plugin.proto.

1. Enable the plugin framework in app.ini:

[plugins]
; Master switch for the plugin framework
ENABLED = true
; Directory for plugin data
PATH = data/plugins
; How often to health-check external plugins
HEALTH_CHECK_INTERVAL = 30s

2. Register external plugins:

Each plugin gets its own [plugins.<name>] section:

[plugins.gitcaddy-ai]
ENABLED = true
; Address of the plugin's gRPC endpoint (cleartext HTTP/2)
ADDRESS = localhost:5000
; Health check timeout
HEALTH_TIMEOUT = 5s
; Events the plugin subscribes to (comma-separated)
SUBSCRIBED_EVENTS = license:updated

Managed vs External Mode:

Mode Configuration Use Case
External ADDRESS only Plugin runs independently (Docker, systemd, sidecar)
Managed BINARY + ARGS Server launches and manages the plugin process

Managed mode example:

[plugins.my-plugin]
ENABLED = true
BINARY = /usr/local/bin/my-plugin
ARGS = --port 5001
ADDRESS = localhost:5001
HEALTH_TIMEOUT = 5s

When a managed plugin becomes unresponsive (3 consecutive health check failures), the server automatically restarts its process.

See PLUGINS.md for the full plugin development guide.

V2 API Configuration

[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. Email is required for account registration, password resets, notification delivery, and blog guest comment verification (anonymous commenters receive a 6-digit code via email to verify their identity).

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

Supported protocols: smtp+starttls (recommended), smtps, smtp, sendmail

Common provider examples:

Provider SMTP_ADDR SMTP_PORT PROTOCOL
Gmail smtp.gmail.com 587 smtp+starttls
Office 365 smtp.office365.com 587 smtp+starttls
Amazon SES email-smtp.us-east-1.amazonaws.com 587 smtp+starttls
Mailgun smtp.mailgun.org 587 smtp+starttls
SendGrid smtp.sendgrid.net 587 smtp+starttls

Note: Gmail requires an App Password (not your regular password) when 2FA is enabled. Amazon SES requires SMTP credentials generated from the SES console.

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.

Monetize / Subscriptions

Gate repository code access (source view, clone, archive downloads) behind paid subscriptions. Issues and releases remain accessible. Supports monthly, yearly, and lifetime pricing tiers with Stripe and PayPal payment providers.

1. Enable the feature in app.ini:

[monetize]
ENABLED = true

2. Configure payment providers in Site Administration > Monetize:

  • Enter your Stripe secret key, publishable key, and webhook secret
  • Enter your PayPal client ID, client secret, and webhook ID
  • Enable each provider individually

3. Enable subscriptions per repository in Repository Settings > Subscriptions > General:

  • Toggle "Enable Subscriptions" for the repository

4. Create subscription products in Repository Settings > Subscriptions > Products:

  • Add monthly, yearly, or lifetime products with pricing
  • Optionally link Stripe Price IDs and PayPal Plan IDs for recurring billing

How it works:

  • Users without an active subscription see a subscribe page (HTTP 402) when accessing gated code
  • Repository owners, admins, collaborators with write access, and site admins bypass the paywall
  • Webhooks from Stripe and PayPal automatically update subscription status (renewals, cancellations, failures)
  • The subscribe page at /{owner}/{repo}/subscribe presents product cards with embedded Stripe Elements and PayPal buttons

Webhook endpoints (configure these in your Stripe/PayPal dashboards):

POST /-/monetize/webhooks/stripe
POST /-/monetize/webhooks/paypal

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
  1. Commit and push the file
  2. Access your landing page at https://your-instance.com/owner/repo/pages

AI Features Usage

Automatic Operations (Event-Driven)

Once AI is enabled on a repo with the desired operations toggled on, these fire automatically:

Event Operations Triggered Tier
New issue created Auto-respond + Auto-triage 1
Comment mentions @gitcaddy-ai Auto-respond 1
Pull request opened Auto-review 1
PR branch updated (push) Auto-review (re-review) 1
Trigger label added to issue Agent fix 2

All operations are queued asynchronously and processed by the AI service. The bot user posts comments/reviews on the issue or PR with the results.

Manual API Triggers

Trigger AI operations on demand via the v2 API:

# Trigger AI code review on a pull request
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/ai/review/1 \
  -H "Authorization: token YOUR_TOKEN"

# Trigger AI response to an issue
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/ai/respond/42 \
  -H "Authorization: token YOUR_TOKEN"

# Trigger AI triage on an issue
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/ai/triage/42 \
  -H "Authorization: token YOUR_TOKEN"

# Explain code in a file
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/ai/explain \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "main.go", "start_line": 10, "end_line": 50, "question": "What does this function do?"}'

# Trigger Tier 2 agent fix (creates a PR)
curl -X POST https://your-instance.com/api/v2/repos/owner/repo/ai/fix/42 \
  -H "Authorization: token YOUR_TOKEN"

All trigger endpoints return 202 Accepted with the queued operation details.

Viewing AI Operation History

Every AI operation is logged with full audit details:

# List operations for a repo (paginated, filterable)
curl "https://your-instance.com/api/v2/repos/owner/repo/ai/operations?status=success&tier=1&page=1" \
  -H "Authorization: token YOUR_TOKEN"

# Get a single operation's details
curl https://your-instance.com/api/v2/repos/owner/repo/ai/operations/123 \
  -H "Authorization: token YOUR_TOKEN"

# Global operation log (site admin only)
curl https://your-instance.com/api/v2/admin/ai/operations \
  -H "Authorization: token YOUR_TOKEN"

Each operation log entry includes: operation type, tier, trigger event, provider, model, input/output tokens, duration, status (success/failed/escalated), and the resulting comment or Actions run ID.

Escalation

When an AI operation fails or returns low confidence, and the repo has escalation configured:

  1. The configured escalation label (e.g., needs-human-review) is added to the issue
  2. The bot posts a summary comment explaining what it attempted and why it's escalating
  3. If an escalation team is configured, a team member is assigned

AI Context APIs (for External AI Tools)

These endpoints provide structured context to external AI tools (IDE plugins, MCP servers, etc.):

# Get repository summary (languages, build system, entry points)
curl -X POST https://your-instance.com/api/v2/ai/repo/summary \
  -H "Authorization: token YOUR_TOKEN" \
  -d '{"owner": "owner", "repo": "repo"}'

# Get issue context (details, comments, complexity hints)
curl -X POST https://your-instance.com/api/v2/ai/issue/context \
  -H "Authorization: token YOUR_TOKEN" \
  -d '{"owner": "owner", "repo": "repo", "issue": 123}'

# Get repository navigation (directory tree, important paths)
curl -X POST https://your-instance.com/api/v2/ai/repo/navigation \
  -H "Authorization: token YOUR_TOKEN" \
  -d '{"owner": "owner", "repo": "repo", "depth": 3}'

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

# AI: Get/update repo AI settings
GET  /api/v2/repos/{owner}/{repo}/ai/settings
PUT  /api/v2/repos/{owner}/{repo}/ai/settings

# AI: Trigger operations
POST /api/v2/repos/{owner}/{repo}/ai/review/{pull}
POST /api/v2/repos/{owner}/{repo}/ai/respond/{issue}
POST /api/v2/repos/{owner}/{repo}/ai/triage/{issue}
POST /api/v2/repos/{owner}/{repo}/ai/explain
POST /api/v2/repos/{owner}/{repo}/ai/fix/{issue}

# AI: Operation audit log
GET  /api/v2/repos/{owner}/{repo}/ai/operations
GET  /api/v2/repos/{owner}/{repo}/ai/operations/{id}

# AI: Org settings
GET  /api/v2/orgs/{org}/ai/settings
PUT  /api/v2/orgs/{org}/ai/settings

# AI: Admin
GET  /api/v2/admin/ai/status
GET  /api/v2/admin/ai/operations

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.

Related Projects:

Project Description
gitcaddy/act_runner Runner with automatic capability detection
gitcaddy/gitcaddy-ai AI sidecar service (.NET 9, gRPC/REST) for code review, triage, and more
gitcaddy/actions-proto-go Protocol buffer definitions for Actions

Support:

Reference in New Issue View Git Blame Copy Permalink