GitCaddy/GitCaddy Server
Limited
2
0
Fork 0
Code Issues Releases 4

docs(nuget): expand ai features documentation
Some checks failed
Build and Release / Create Release (push) Successful in 1s
Details
Build and Release / Unit Tests (push) Successful in 6m48s
Details
Build and Release / Integration Tests (PostgreSQL) (push) Successful in 6m59s
Details
Build and Release / Lint (push) Successful in 7m18s
Details
Build and Release / Build Binaries (amd64, linux, linux-latest) (push) Successful in 3m17s
Details
Build and Release / Build Binaries (amd64, darwin, macos) (push) Successful in 6m14s
Details
Build and Release / Build Binaries (arm64, darwin, macos) (push) Successful in 5m41s
Details
Build and Release / Build Binary (linux/arm64) (push) Failing after 6m9s
Details
Build and Release / Build Binaries (amd64, windows, windows-latest) (push) Failing after 8h4m30s
Details

Browse Source 
Significantly expand the AI features section of the README with comprehensive configuration and usage documentation.

New content includes:
- Detailed explanation of Tier 1 (light operations) vs Tier 2 (agent mode)
- Complete app.ini configuration reference with all AI settings
- Step-by-step setup guide (system → org → repo → runner)
- Configuration cascade explanation (repo > org > system)
- Built-in safety features (bot user, loop prevention, rate limits, escalation)
- Automatic operation triggers table
- Manual API trigger examples
- Operation history and audit log access
- Escalation workflow documentation
- V2 API configuration section

This provides users with everything needed to deploy and configure the AI features, from initial setup through advanced agent mode configuration.
This commit is contained in:
David H. Friedel Jr.
2026-02-12 09:38:12 -05:00
parent 14338d8fd4
commit 813e3bcbb4
1 changed files with 224 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
README.md
View File

@@ -17,6 +17,10 @@ The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-as
- [Package Registry](#package-registry)
- [Vault System (Pro/Enterprise)](#vault-system-proenterprise)
- [AI-Powered Features](#ai-powered-features)
- [Tier 1 - Light Operations](#ai-powered-features)
- [Tier 2 - Agent Operations](#ai-powered-features)
- [Configuration Cascade](#ai-powered-features)
- [Built-in Safety](#ai-powered-features)
- [Landing Pages & Public Releases](#landing-pages--public-releases)
- [App Update API (Electron/Squirrel Compatible)](#app-update-api-electronsquirrel-compatible)
- [Release Archive](#release-archive)
@@ -30,6 +34,7 @@ The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-as
- [Configuration](#configuration)
- [Database Setup](#database-setup)
- [AI Features Configuration](#ai-features-configuration)
- [V2 API Configuration](#v2-api-configuration)
- [Authentication Sources](#authentication-sources)
- [Email/SMTP Setup](#emailsmtp-setup)
- [Unsplash Integration](#unsplash-integration)
@@ -42,6 +47,11 @@ The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-as
- [Vault Usage (Pro/Enterprise)](#vault-usage-proenterprise)
- [Landing Pages Configuration](#landing-pages-configuration)
- [AI Features Usage](#ai-features-usage)
- [Automatic Operations](#automatic-operations-event-driven)
- [Manual API Triggers](#manual-api-triggers)
- [Viewing AI Operation History](#viewing-ai-operation-history)
- [Escalation](#escalation)
- [AI Context APIs](#ai-context-apis-for-external-ai-tools)
- [GitCaddy Runner](#gitcaddy-runner)
- [API Documentation](#api-documentation)
- [Internationalization](#internationalization)
@@ -262,10 +272,30 @@ Enterprise-grade encrypted secrets management:
### 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
GitCaddy integrates with the [gitcaddy-ai](https://git.marketally.com/gitcaddy/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
### Landing Pages & Public Releases
@@ -492,15 +522,95 @@ SSL_MODE = disable
### AI Features Configuration
Enable and configure AI-powered features in `app.ini`:
AI features require the [gitcaddy-ai](https://git.marketally.com/gitcaddy/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`:**
```ini
[server]
ROOT_URL = https://your-instance.com/
[actions]
[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.
### V2 API Configuration
```ini
[api]
; Enable V2 API (enabled by default)
ENABLE_V2_API = true
@@ -800,36 +910,96 @@ advanced:
### 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
#### Automatic Operations (Event-Driven)
**Issue Triage:**
- AI automatically categorizes new issues
- Suggests labels based on content
- Estimates complexity
- Recommends relevant files for investigation
Once AI is enabled on a repo with the desired operations toggled on, these fire automatically:
**Code Explanation:**
1. Select code in the file viewer
2. Click "Explain with AI"
3. View generated documentation
| 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:
**Using AI Context APIs:**
```bash
# Get repository summary
curl https://your-instance.com/api/v2/ai/repo/summary?owner=owner&repo=repo \
# 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"
# Get issue context
curl https://your-instance.com/api/v2/ai/issue/context?owner=owner&repo=repo&issue=123 \
# 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"
# Get repository navigation
curl https://your-instance.com/api/v2/ai/repo/navigation?owner=owner&repo=repo&depth=3 \
# 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:
```bash
# 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.):
```bash
# 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
@@ -924,6 +1094,29 @@ 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
@@ -1060,6 +1253,7 @@ GitCaddy is a fork of [Gitea](https://gitea.io), the open-source self-hosted Git
| Project | Description |
|---------|-------------|
| [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with automatic capability detection |
| [gitcaddy/gitcaddy-ai](https://git.marketally.com/gitcaddy/gitcaddy-ai) | AI sidecar service (.NET 9, gRPC/REST) for code review, triage, and more |
| [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol buffer definitions for Actions |
**Support:**