aiworker/GITEA-GUIDE.md

# 📚 Gitea - Guía Completa de Uso

Toda la información de Gitea en un solo lugar: autenticación, API, registry, webhooks, y CI/CD.

---

## 🌐 Acceso Web

**URL**: https://git.fuq.tv

**Credenciales Admin**:
- Usuario: `admin`
- Password: `admin123`

**Primera vez**: Ya configurado, listo para usar.

---

## 🔑 Autenticación y Tokens

### Tokens Existentes

| Nombre | Token | Scopes | Uso |
|--------|-------|--------|-----|
| full-access | `159a5de2a16d15f33e388b55b1276e431dbca3f3` | all | API completa |
| docker-registry | `7401126cfb56ab2aebba17755bdc968c20768c27` | write:package, read:package | Container registry |

### Crear Nuevo Token (CLI)

```bash
# Desde el pod de Gitea
kubectl exec -n gitea gitea-0 -- su git -c "gitea admin user generate-access-token \
  --username admin \
  --scopes all \
  --token-name my-token \
  --raw"
```

### Crear Token (Web UI)

1. Login en https://git.fuq.tv
2. Perfil → Settings → Applications
3. Generate New Token
4. Seleccionar scopes necesarios
5. Copiar token (solo se muestra una vez)

**Scopes importantes**:
- `write:repository` - Crear repos, push
- `write:package` - Push imágenes Docker
- `read:package` - Pull imágenes Docker
- `write:issue` - Gestionar issues
- `write:user` - Operaciones de usuario
- `all` - Acceso completo

---

## 🐳 Container Registry

### Configuración

**Registry URL**: `git.fuq.tv`
**Formato de imágenes**: `git.fuq.tv/<owner>/<package>:<tag>`

### Login Docker

```bash
# Con token de registry
docker login git.fuq.tv -u admin -p 7401126cfb56ab2aebba17755bdc968c20768c27

# O de forma segura
echo "7401126cfb56ab2aebba17755bdc968c20768c27" | docker login git.fuq.tv -u admin --password-stdin
```

### Build y Push

```bash
# Build
docker build -t git.fuq.tv/admin/aiworker-backend:v1.0.0 .

# Push
docker push git.fuq.tv/admin/aiworker-backend:v1.0.0

# Tag como latest
docker tag git.fuq.tv/admin/aiworker-backend:v1.0.0 git.fuq.tv/admin/aiworker-backend:latest
docker push git.fuq.tv/admin/aiworker-backend:latest
```

### Pull

```bash
docker pull git.fuq.tv/admin/aiworker-backend:latest
```

### Ver Imágenes (UI)

1. https://git.fuq.tv
2. Perfil → Packages
3. O: https://git.fuq.tv/admin/-/packages

### Kubernetes Pull Secret

**Ya creado** en namespaces `control-plane` y `agents`:

```bash
# Verificar
kubectl get secret gitea-registry -n control-plane

# Crear en nuevo namespace
kubectl create secret docker-registry gitea-registry \
  --docker-server=git.fuq.tv \
  --docker-username=admin \
  --docker-password=7401126cfb56ab2aebba17755bdc968c20768c27 \
  --docker-email=hector@teamsuqad.io \
  -n <namespace>
```

**Uso en deployment**:
```yaml
spec:
  template:
    spec:
      imagePullSecrets:
      - name: gitea-registry
      containers:
      - name: app
        image: git.fuq.tv/admin/myapp:latest
```

---

## 🔌 API de Gitea

**Base URL**: `https://git.fuq.tv/api/v1`
**Documentación**: https://git.fuq.tv/api/swagger

### Autenticación API

**Header**:
```
Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3
```

### Ejemplos de Uso

#### Crear Repositorio

```bash
curl -X POST "https://git.fuq.tv/api/v1/user/repos" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-repo",
    "description": "My description",
    "private": false,
    "auto_init": true
  }'
```

#### Listar Repositorios

```bash
curl "https://git.fuq.tv/api/v1/user/repos" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3"
```

#### Crear Branch

```bash
curl -X POST "https://git.fuq.tv/api/v1/repos/admin/myrepo/branches" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "new_branch_name": "feature-x",
    "old_branch_name": "main"
  }'
```

#### Crear Pull Request

```bash
curl -X POST "https://git.fuq.tv/api/v1/repos/admin/myrepo/pulls" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My PR",
    "body": "Description",
    "head": "feature-x",
    "base": "main"
  }'
```

#### Merge Pull Request

```bash
curl -X POST "https://git.fuq.tv/api/v1/repos/admin/myrepo/pulls/1/merge" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "Do": "merge",
    "merge_when_checks_succeed": false
  }'
```

### Cliente TypeScript (Backend)

**Ubicación**: `backend/src/services/gitea/client.ts`

**Uso**:
```typescript
import { GiteaClient } from './services/gitea/client'

const gitea = new GiteaClient({
  url: 'https://git.fuq.tv',
  token: process.env.GITEA_TOKEN,
  owner: 'admin'
})

// Crear repo
const repo = await gitea.createRepo('my-app', {
  description: 'My application',
  private: false,
  autoInit: true
})

// Crear branch
await gitea.createBranch('admin', 'my-app', 'feature-auth', 'main')

// Crear PR
const pr = await gitea.createPullRequest('admin', 'my-app', {
  title: 'Add authentication',
  body: 'Implements JWT auth',
  head: 'feature-auth',
  base: 'main'
})
```

**Referencia completa**: `docs/02-backend/gitea-integration.md`

---

## 🪝 Webhooks

### Configurar Webhook (API)

```bash
curl -X POST "https://git.fuq.tv/api/v1/repos/admin/myrepo/hooks" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "gitea",
    "config": {
      "url": "https://api.fuq.tv/api/webhooks/gitea",
      "content_type": "json",
      "secret": "webhook-secret-123"
    },
    "events": ["push", "pull_request"],
    "active": true
  }'
```

### Handler Backend

```typescript
// backend/src/api/routes/webhooks.ts
export async function handleGiteaWebhook(req: Request) {
  const signature = req.headers.get('x-gitea-signature')
  const event = req.headers.get('x-gitea-event')
  const payload = await req.json()

  // Verify signature
  // ... verification logic

  switch (event) {
    case 'push':
      await handlePushEvent(payload)
      break
    case 'pull_request':
      await handlePREvent(payload)
      break
  }

  return Response.json({ success: true })
}
```

**Eventos importantes**:
- `push` - Nuevo commit
- `pull_request` - PR creado/actualizado
- `pull_request_closed` - PR cerrado/mergeado

---

## 🔄 Gitea Actions (CI/CD)

### Workflow File

**Ubicación**: `.gitea/workflows/<name>.yml`

**Ejemplo** (Build Docker image):
```yaml
name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build image
        run: docker build -t git.fuq.tv/admin/myapp:latest .

      - name: Login to registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.fuq.tv -u admin --password-stdin

      - name: Push image
        run: docker push git.fuq.tv/admin/myapp:latest
```

### Secrets en Repositorio

**Crear secret** (API):
```bash
curl -X PUT "https://git.fuq.tv/api/v1/repos/admin/myrepo/actions/secrets/MY_SECRET" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{"data":"my-secret-value"}'
```

**Crear secret** (Web UI):
1. Repo → Settings → Secrets → Actions
2. Add Secret
3. Name: `REGISTRY_TOKEN`
4. Value: `7401126cfb56ab2aebba17755bdc968c20768c27`

**Uso en workflow**:
```yaml
- name: Use secret
  run: echo "${{ secrets.REGISTRY_TOKEN }}"
```

### Ver Workflows

**UI**: https://git.fuq.tv/admin/<repo>/actions

**Runner logs** (K8s):
```bash
kubectl logs -n gitea-actions deployment/gitea-runner -c runner --tail=100
```

### Runner Status

**Verificar runner activo**:
```bash
kubectl get pods -n gitea-actions

# Logs
kubectl logs -n gitea-actions deployment/gitea-runner -c runner

# Restart si es necesario
kubectl rollout restart deployment/gitea-runner -n gitea-actions
```

**Ver en UI**: https://git.fuq.tv/admin/runners

---

## 👥 Gestión de Usuarios

### Crear Usuario (CLI)

```bash
kubectl exec -n gitea gitea-0 -- su git -c "gitea admin user create \
  --username myuser \
  --password mypass123 \
  --email user@example.com \
  --admin"
```

### Cambiar Password

```bash
kubectl exec -n gitea gitea-0 -- su git -c "gitea admin user change-password \
  --username admin \
  --password newpassword"
```

### Listar Usuarios

```bash
kubectl exec -n gitea gitea-0 -- su git -c "gitea admin user list"
```

---

## 📂 Organizaciones

### Crear Organización (API)

```bash
curl -X POST "https://git.fuq.tv/api/v1/orgs" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "aiworker",
    "full_name": "AiWorker Organization",
    "description": "AiWorker platform repos"
  }'
```

### Crear Repo en Organización

```bash
curl -X POST "https://git.fuq.tv/api/v1/org/aiworker/repos" \
  -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "auto_init": true
  }'
```

---

## 🔧 Configuración de Gitea

### Ver Configuración Actual

```bash
kubectl exec -n gitea gitea-0 -- cat /data/gitea/conf/app.ini
```

### Configuración Importante

**Database**:
```ini
[database]
DB_TYPE = mysql
HOST = mariadb.control-plane.svc.cluster.local:3306
NAME = gitea
USER = root
PASSWD = AiWorker2026_RootPass!
```

**Server**:
```ini
[server]
DOMAIN = git.fuq.tv
ROOT_URL = https://git.fuq.tv/
HTTP_PORT = 3000
SSH_PORT = 2222
```

**Packages** (Container Registry):
```ini
[packages]
ENABLED = true
```

### Restart Gitea

```bash
kubectl delete pod gitea-0 -n gitea
# Esperar a que se recree automáticamente
```

---

## 🔐 SSH Access a Repos

### SSH URL Format

```
ssh://git@git.fuq.tv:2222/<owner>/<repo>.git
```

### SSH Clone

```bash
# Nota: Puerto 2222, no 22
git clone ssh://git@git.fuq.tv:2222/admin/aiworker-backend.git
```

### Agregar SSH Key (UI)

1. Login → Settings → SSH/GPG Keys
2. Add Key
3. Paste public key

### Agregar SSH Key (CLI)

```bash
# Generar key
ssh-keygen -t ed25519 -C "agent@aiworker.dev" -f ~/.ssh/gitea_key

# Agregar a Gitea (manual en UI o via API)
```

---

## 🎬 Gitea Actions - Guía Completa

### Runner en K8s

**Namespace**: `gitea-actions`
**Pod**: `gitea-runner-*`

**Status**:
```bash
kubectl get pods -n gitea-actions
kubectl logs -n gitea-actions deployment/gitea-runner -c runner
```

### Workflow Syntax

Compatible con GitHub Actions. Ubicación: `.gitea/workflows/*.yml`

**Triggers**:
```yaml
on:
  push:
    branches: [main, develop]
    tags: ['v*']
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * *'  # Diario
```

**Jobs**:
```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run script
        run: echo "Hello"
```

### Actions Disponibles

Compatible con GitHub Actions marketplace:
- `actions/checkout@v4`
- `docker/build-push-action@v5`
- `docker/login-action@v3`
- Y muchas más

### Secrets en Actions

**Acceso**:
```yaml
- name: Use secret
  run: echo "${{ secrets.MY_SECRET }}"
  env:
    API_KEY: ${{ secrets.API_KEY }}
```

**Secrets necesarios para builds**:
- `REGISTRY_TOKEN` - Ya configurado en `aiworker-backend`

### Variables de Entorno Automáticas

```yaml
${{ github.repository }}      # admin/aiworker-backend
${{ github.sha }}              # Commit hash
${{ github.ref }}              # refs/heads/main
${{ github.actor }}            # Usuario que hizo push
${{ github.event_name }}       # push, pull_request, etc.
```

### Debug de Workflows

```bash
# Ver en UI
https://git.fuq.tv/admin/<repo>/actions/runs/<run-id>

# Ver runner logs
kubectl logs -n gitea-actions deployment/gitea-runner -c runner --tail=200

# Ver Docker daemon logs
kubectl logs -n gitea-actions deployment/gitea-runner -c dind --tail=50
```

---

## 🛠️ Operaciones Comunes desde Backend

### Inicializar Proyecto Nuevo

```typescript
// 1. Crear repo en Gitea
const repo = await giteaClient.createRepo('my-project', {
  description: 'Project description',
  autoInit: true
})

// 2. Setup webhooks
await giteaClient.createWebhook('admin', 'my-project', {
  url: 'https://api.fuq.tv/api/webhooks/gitea',
  events: ['push', 'pull_request']
})

// 3. Guardar en DB
await db.insert(projects).values({
  id: crypto.randomUUID(),
  name: 'my-project',
  giteaRepoUrl: repo.clone_url,
  giteaOwner: 'admin',
  giteaRepoName: 'my-project'
})
```

### Workflow de Tarea Completa

```typescript
// 1. Obtener tarea
const task = await db.query.tasks.findFirst({
  where: eq(tasks.state, 'backlog')
})

// 2. Crear branch para tarea
await giteaClient.createBranch(
  project.giteaOwner,
  project.giteaRepoName,
  `task-${task.id}`,
  'main'
)

// 3. Agente trabaja (commits via git)...

// 4. Crear PR
const pr = await giteaClient.createPullRequest(
  project.giteaOwner,
  project.giteaRepoName,
  {
    title: task.title,
    body: task.description,
    head: `task-${task.id}`,
    base: 'main'
  }
)

// 5. Guardar PR URL
await db.update(tasks)
  .set({ prUrl: pr.html_url })
  .where(eq(tasks.id, task.id))
```

### Merge Automático

```typescript
await giteaClient.mergePullRequest(
  'admin',
  'my-project',
  prNumber,
  'squash'  // o 'merge', 'rebase'
)
```

---

## 🗂️ Estructura de Archivos en Gitea

### En el Pod

```bash
# Datos de Gitea
/data/gitea/
├── conf/app.ini        # Configuración
├── log/                # Logs
├── git/repositories/   # Repos Git
├── git/lfs/            # Git LFS
├── packages/           # Container registry
└── attachments/        # Uploads

# Ejecutable
/usr/local/bin/gitea
```

### Comandos CLI de Gitea

```bash
# Todos los comandos deben ejecutarse como usuario 'git'
kubectl exec -n gitea gitea-0 -- su git -c "gitea <command>"

# Ejemplos:
gitea admin user list
gitea admin user create --username x --password y --email z
gitea admin regenerate keys
gitea dump  # Backup completo
```

---

## 📊 Monitoring y Maintenance

### Logs de Gitea

```bash
# Logs del contenedor
kubectl logs -n gitea gitea-0 --tail=100 -f

# Logs de aplicación (dentro del pod)
kubectl exec -n gitea gitea-0 -- tail -f /data/gitea/log/gitea.log
```

### Health Check

```bash
# HTTP health
curl https://git.fuq.tv/api/healthz

# Database connection
kubectl exec -n gitea gitea-0 -- su git -c "gitea doctor check --run"
```

### Backup

```bash
# Backup completo (crea archivo .zip)
kubectl exec -n gitea gitea-0 -- su git -c "gitea dump -f /tmp/gitea-backup.zip"

# Copiar backup fuera
kubectl cp gitea/gitea-0:/tmp/gitea-backup.zip ./gitea-backup-$(date +%Y%m%d).zip
```

### Storage

**PVC**: 50Gi con Longhorn (3 réplicas HA)

```bash
# Ver PVC
kubectl get pvc -n gitea

# Ver volumen Longhorn
kubectl get volumes.longhorn.io -n longhorn-system | grep gitea

# Ver réplicas
kubectl get replicas.longhorn.io -n longhorn-system | grep $(kubectl get pvc -n gitea gitea-data -o jsonpath='{.spec.volumeName}')
```

---

## 🚀 Quick Actions

### Crear Proyecto Completo (Script)

```bash
#!/bin/bash
PROJECT_NAME="my-project"
TOKEN="159a5de2a16d15f33e388b55b1276e431dbca3f3"

# 1. Crear repo
curl -X POST "https://git.fuq.tv/api/v1/user/repos" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"$PROJECT_NAME\",\"auto_init\":true}"

# 2. Crear webhook
curl -X POST "https://git.fuq.tv/api/v1/repos/admin/$PROJECT_NAME/hooks" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"gitea","config":{"url":"https://api.fuq.tv/webhooks/gitea","content_type":"json"},"events":["push","pull_request"],"active":true}'

# 3. Clone
git clone https://git.fuq.tv/admin/$PROJECT_NAME.git
cd $PROJECT_NAME

# 4. Crear workflow
mkdir -p .gitea/workflows
cat > .gitea/workflows/build.yml << 'EOF'
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Build steps here"
EOF

git add .gitea && git commit -m "Add CI/CD" && git push
```

---

## 🎯 Resumen de URLs y Credenciales

### Web UI
- **Gitea**: https://git.fuq.tv
- **Login**: admin / admin123
- **Settings**: https://git.fuq.tv/user/settings
- **Packages**: https://git.fuq.tv/admin/-/packages
- **Actions**: https://git.fuq.tv/admin/<repo>/actions

### API
- **Base**: https://git.fuq.tv/api/v1
- **Swagger**: https://git.fuq.tv/api/swagger
- **Token Full**: `159a5de2a16d15f33e388b55b1276e431dbca3f3`

### Registry
- **URL**: git.fuq.tv
- **Token**: `7401126cfb56ab2aebba17755bdc968c20768c27`
- **Format**: `git.fuq.tv/<owner>/<image>:<tag>`

### SSH
- **URL**: `ssh://git@git.fuq.tv:2222/<owner>/<repo>.git`
- **Port**: 2222 (no 22)

---

## 💡 Tips

1. **Tokens**: Full access token para API, registry token solo para Docker
2. **Branches**: Siempre desde `main` a menos que especifique otro
3. **PRs**: Usar `squash` merge para historial limpio
4. **Webhooks**: Verificar que `ALLOWED_HOST_LIST` incluye tu dominio
5. **Actions**: Primer build tarda más (descarga imágenes)
6. **Registry**: Las imágenes se guardan en Longhorn HA storage

---

**📖 Referencia completa**: `docs/02-backend/gitea-integration.md` y `docs/CONTAINER-REGISTRY.md`

**🔧 Para implementar en backend**: Ver código de ejemplo en `docs/02-backend/gitea-integration.md` líneas 5-400