gitea-infrastructure/HANDOVER.md

Gitea Infrastructure Handover Document

Overview

Self-hosted Gitea instance running on bigbox server with S3 storage, PostgreSQL, and Prometheus monitoring.

URL: https://git.terraphim.cloud GitHub Mirror: https://github.com/terraphim/gitea-infrastructure

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Internet                              │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS (port 443)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Caddy Reverse Proxy                      │
│                  (terraphim.cloud, existing)                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ git.terraphim.cloud -> localhost:3000
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Docker Network (gitea)                   │
├─────────────────────────────────────────────────────────────┤
│  Gitea (port 3000)  │  PostgreSQL  │  SeaweedFS (S3)        │
│  - Attachments      │  (port 5432) │  - S3 (port 8333)      │
│  - Avatars          │              │  - Filer (port 8888)    │
│  - LFS              │              │  - Volume (port 8080)     │
│                     │              │  - Master (port 9333)   │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Tailscale Network                         │
│           Prometheus (100.106.66.7:9000) - internal         │
│           S3 (100.106.66.7:8333) - internal only             │
└─────────────────────────────────────────────────────────────┘

Services

Service	Port	Access	Description
Gitea	3000	localhost (via Caddy)	Git web UI
Gitea SSH	22/222	Public	Git over SSH
PostgreSQL	5432	Docker internal	Database
SeaweedFS S3	8333	Tailscale only	S3-compatible storage
SeaweedFS Filer	8888	Docker internal	File interface
Prometheus	9000	Tailscale only	Metrics

Server Access

Server: bigbox (100.106.66.7)

# SSH to bigbox
ssh bigbox

# Navigate to stack directory
cd ~/gitea-stack

# View container status
docker compose ps

# View logs
docker compose logs -f gitea

# Restart Gitea
docker compose restart server

# Stop entire stack
docker compose down

# Start stack
docker compose up -d

1Password Secrets

Vault: TerraphimPlatform

Item	Purpose
gitea-postgres	PostgreSQL password
gitea-s3	S3 access key and secret key

Re-deploying with 1Password

1. Source the 1Password authentication:

   source ~/op_zesticai_non_prod.sh
   

2. Inject secrets and deploy:

   cd ~/gitea-stack
   op inject --in-file ../gitea_config/docker-compose.yml.template --out-file docker-compose.yml
   docker compose up -d
   

Storage Configuration

S3 Buckets

• gitea - Attachments, avatars, repository files
• gitea-lfs - Git LFS objects

Gitea Storage Settings

The following storage types are configured to use S3 (Minio):

• [attachment] - File attachments
• [picture] - Avatars and images
• [lfs] - Git LFS objects
• [storage] - Default storage configuration

Local storage is used for:

• Git repositories (/data/git/repositories)
• Database (PostgreSQL)

Caddy Configuration

Caddy is already running on bigbox. The git route is appended to /etc/caddy/Caddyfile:

git.terraphim.cloud {
    reverse_proxy localhost:3000
}

To update Caddy config:

ssh bigbox
sudo vim /etc/caddy/Caddyfile
sudo caddy reload

Monitoring

Prometheus: http://100.106.66.7:9000 (Tailscale only)

Scrape targets configured in prometheus/prometheus.yml.

Troubleshooting

Check Gitea status

ssh bigbox
docker compose ps
docker logs gitea

Check S3 connectivity

ssh bigbox
docker exec gitea curl -s http://s3storage:8333/

Reset PostgreSQL password

ssh bigbox
docker compose exec db psql -U gitea -c "ALTER USER gitea WITH PASSWORD 'newpassword';"

View S3 buckets

ssh bigbox
curl -s http://localhost:8888/bucket/

Backup

To back up the Gitea data:

# On bigbox
cd ~/gitea-stack
docker compose stop
tar -czf gitea-backup-$(date +%Y%m%d).tar.gz gitea/ postgres/ seaweedfs/
docker compose start

Updates

To update Gitea to a new version:

1. Edit docker-compose.yml.template:

   image: gitea/gitea:NEW_VERSION
   

2. Re-inject secrets and deploy:

   source ~/op_zesticai_non_prod.sh
   op inject --in-file ../gitea_config/docker-compose.yml.template --out-file docker-compose.yml
   docker compose up -d --build
   

GitHub Mirroring

See MIRRORING-GUIDE.md for bidirectional GitHub ↔ Gitea mirroring setup.

AI Agent Skill (Gitea Task Management)

Added 2026-02-18. Provides AI agents with project and task management via Gitea API.

Architecture

Dual-mode: gitea-mcp (75+ tools for standard CRUD) + curl/jq shell helpers (milestones, workflow labels, dependencies -- areas where gitea-mcp has gaps).

Key Constraint

Gitea 1.22.6 has NO project board REST API. Milestones serve as project containers with built-in progress tracking.

Files

File	Description
.agents/skills/gitea/SKILL.md	Agent skill document with all helpers
.agents/skills/gitea/setup-labels.sh	Idempotent repo + 12 label creation
.agents/skills/gitea/test-gitea-skill.sh	10 integration tests (26 assertions)
.docs/RESEARCH-gitea-agent-skill.md	Phase 1 research (verified against live)
.docs/DESIGN-gitea-agent-skill.md	Phase 2 design document

Default Task Repository

terraphim/agent-tasks -- overridable via GITEA_OWNER and GITEA_REPO env vars.

Authentication

source ~/op_zesticai_non_prod.sh
export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")

Workflow Labels

12 scoped labels across 3 scopes (workflow, priority, type). Workflow state machine: ready -> in-progress -> blocked -> done.

Running Tests

source ~/op_zesticai_non_prod.sh
export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")
.agents/skills/gitea/test-gitea-skill.sh

All 26 assertions pass against live Gitea 1.22.6 as of 2026-02-18.

Critical API Gotchas

1. Label exclusivity is UI-only -- API POST /labels just appends. Must use PUT with label swap pattern (get current, filter workflow:*, add new, PUT all).
2. Assignees -- Use PATCH /issues/{index} with {"assignees": [...]}. The POST /issues/{index}/assignees endpoint does not exist in 1.22.6.
3. Issue dependencies -- Body uses IssueMeta format: {"owner": "...", "repo": "...", "index": N} (NOT {"depends_on_id": N}).

Pre-commit Hooks

Added .pre-commit-config.yaml with:

• Trailing whitespace, end-of-file fixer, YAML/JSON check
• Merge conflict and private key detection
• Secret detection via detect-secrets (baseline at .secrets.baseline)

Key Files

File	Description
docker-compose.yml.template	Template with 1Password references
Caddyfile	Caddy reverse proxy config
deploy-to-bigbox.sh	Deployment script
s3_config.json.template	SeaweedFS S3 config template
prometheus/prometheus.yml	Prometheus scrape config
.github/workflows/*.yml	GitHub Actions for mirroring
.agents/skills/gitea/SKILL.md	AI agent Gitea skill
.agents/skills/gitea/setup-labels.sh	Label setup script
.agents/skills/gitea/test-gitea-skill.sh	Integration tests
.pre-commit-config.yaml	Pre-commit hook config
ARTICLE-agent-task-management.md	CTO voice article (~2800 words)
ARTICLE-agent-task-consolidation.md	Technical reference article (~6000 words)
lessons-learned.md	Session discoveries and pitfalls

Articles

Two comparison articles documenting the migration from beads/br/agent-mail to Gitea:

File	Style	Words
ARTICLE-agent-task-management.md	CTO voice (bold, narrative)	~2800
ARTICLE-agent-task-consolidation.md	Technical reference (comprehensive)	~6000

Both cover: 1Password integration, Gitea + SeaweedFS infrastructure, all three API gotchas with fix patterns, and honest tradeoff analysis. All commands verified working against live instance.

Gitea Mirror

The gitea-infrastructure repo is now published on both remotes:

Remote	URL
GitHub (origin)	https://github.com/terraphim/gitea-infrastructure
Gitea	https://git.terraphim.cloud/terraphim/gitea-infrastructure

Note: The sync-to-gitea.yml GitHub Actions workflow is failing due to a billing/spending limit issue. Direct push via op token was used as workaround. Check GitHub Settings > Billing & plans to restore automated sync.

Session Log (2026-02-18)

Session 1: Gitea Agent Skill Implementation

• Rewrote Gitea agent skill with verified API patterns (milestones, workflow labels, dependencies)
• Created setup-labels.sh for idempotent repo + label creation
• Created test-gitea-skill.sh with 10 tests (26 assertions), all passing
• Found and fixed 3 API behavior bugs (label exclusivity, assignee endpoint, dependency format)
• Added pre-commit hooks and fixed trailing whitespace across 15 files
• Conducted disciplined research and design phases with live API verification

Session 2: Articles and Publishing

• Wrote two comparison articles (CTO voice + technical reference) comparing beads/br/agent-mail with Gitea replacement
• All code snippets, commands, and configurations verified against live Gitea instance
• Pushed all commits to GitHub origin/main
• Created gitea-infrastructure repo on Gitea and pushed full history
• Discovered GitHub Actions billing issue blocking automated sync-to-gitea workflow

All Commits (pushed)

• 62e2275 docs: Add articles comparing beads/br/agent-mail with Gitea replacement
• 4ff1821 docs: Update handover and add lessons learned
• b67284e chore: Fix trailing whitespace across project files
• 66b305d feat(gitea-skill): Add integration tests and fix workflow label swap
• 1fd202d feat(gitea-skill): Rewrite Gitea agent skill with verified API patterns

Next Steps

1. Fix GitHub Actions billing to restore automated Gitea sync
2. Consider adding gitea-mcp or forgejo-mcp as MCP server for Claude Code (see SKILL.md MCP Integration section)
3. Create first real milestone and tasks in terraphim/agent-tasks for a project
4. Consider Phase 4 (disciplined-verification) if more rigorous validation is needed

Contacts

• Infrastructure owner: Alex
• 1Password vault: TerraphimPlatform