aiworker/DEVELOPMENT-WORKFLOW.md

🔄 Development Workflow - Cómo Trabajamos

Flujo completo de desarrollo usando Gitea, container registry y CI/CD automático.

---

📋 Overview del Workflow

Local Dev → Git Push → Gitea Actions → Docker Build → Registry Push → K8s Deploy

Principios:

• ✅ CI/CD automático - Cada push buildea automáticamente
• ✅ Registry integrado - Imágenes en Gitea, no Docker Hub
• ✅ GitOps - ArgoCD sincroniza desde Git
• ✅ Sin Docker local - Builds en el cluster
• ✅ Preview automático - Cada tarea tiene su environment

---

🛠️ Workflow Típico: Nueva Feature

1. Desarrollo Local

# Backend
cd backend
bun run dev  # Hot reload activado

# Test localmente
curl http://localhost:3000/api/health

Conexión a servicios K8s (solo para desarrollo):

# Terminal 1: MariaDB
kubectl port-forward -n control-plane svc/mariadb 3306:3306

# Terminal 2: Redis
kubectl port-forward -n control-plane svc/redis 6379:6379

# Ahora el backend local puede conectar a DB/Redis en K8s

2. Commit y Push

git add .
git commit -m "Add feature X

Detailed description

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>"
git push origin main

3. CI/CD Automático (Gitea Actions)

Qué pasa automáticamente:

1. Gitea recibe push
2. Workflow .gitea/workflows/build.yml se ejecuta
3. Runner en K8s (pod con Docker) buildea imagen
4. Push a git.fuq.tv/admin/<repo>:latest
5. Tag adicional con commit hash: git.fuq.tv/admin/<repo>:<sha>

Monitorear:

# Ver en UI
open https://git.fuq.tv/admin/aiworker-backend/actions

# Ver logs del runner
kubectl logs -n gitea-actions deployment/gitea-runner -c runner --tail=100 -f

Tiempo típico: 2-5 minutos (primer build más lento)

4. Verificar Imagen en Registry

# Ver en UI
open https://git.fuq.tv/admin/-/packages

# O via API
curl -H "Authorization: token 159a5de2a16d15f33e388b55b1276e431dbca3f3" \
  https://git.fuq.tv/api/v1/packages/admin/container

Debe aparecer: aiworker-backend con tags latest y <commit-hash>

5. Deploy en K8s (manual por ahora, ArgoCD después)

# Aplicar manifests
kubectl apply -f k8s/backend/

# O update imagen específica
kubectl set image deployment/backend backend=git.fuq.tv/admin/aiworker-backend:latest -n control-plane

# Verificar rollout
kubectl rollout status deployment/backend -n control-plane

# Ver logs
kubectl logs -f deployment/backend -n control-plane

6. Verificar en Producción

# Health check
curl https://api.fuq.tv/api/health

# Test endpoints
curl https://api.fuq.tv/api/projects

---

🌿 Workflow: Feature Branch

1. Crear Branch

git checkout -b feature/nueva-funcionalidad

2. Desarrollar y Commit

# Hacer cambios
bun run dev  # Test local

git add .
git commit -m "Implement nueva funcionalidad"
git push origin feature/nueva-funcionalidad

3. Crear Pull Request

Opción A - UI:

1. https://git.fuq.tv/admin/aiworker-backend
2. "New Pull Request"
3. Base: main ← Compare: feature/nueva-funcionalidad

Opción B - API (desde backend):

const pr = await giteaClient.createPullRequest('admin', 'aiworker-backend', {
  title: 'Nueva funcionalidad',
  body: 'Descripción detallada',
  head: 'feature/nueva-funcionalidad',
  base: 'main'
})

4. Review y Merge

Manual (UI):

• Review code
• Click "Merge Pull Request"

Automático (via backend):

await giteaClient.mergePullRequest('admin', 'aiworker-backend', prNumber, 'squash')

5. Deploy Automático post-Merge

Una vez mergeado a main, el CI/CD rebuildeará automáticamente.

---

🚀 Workflow: Deploy de Preview

Para cada tarea, se crea un preview environment aislado.

Proceso Completo

// 1. Agente completa tarea
// 2. Crea branch y PR (via MCP)

// 3. Backend crea preview deployment
const previewNamespace = `preview-task-${taskId.slice(0, 8)}`

// Crear namespace en K8s
await k8sClient.createNamespace(previewNamespace)

// Deploy app
await k8sClient.createDeployment({
  namespace: previewNamespace,
  name: 'app',
  image: `git.fuq.tv/admin/aiworker-backend:${branchName}`,
  // ... config
})

// Crear ingress
await k8sClient.createIngress({
  namespace: previewNamespace,
  host: `task-${taskId.slice(0, 8)}.r.fuq.tv`,
  // ... config
})

// 4. Usuario accede a:
// https://task-abc12345.r.fuq.tv

// 5. Si aprueba → merge a staging
// 6. Cleanup automático después de 7 días

---

🎨 Workflow: Multi-Repo

Eventualmente tendremos múltiples repos:

/admin/aiworker-backend    → Backend API
/admin/aiworker-frontend   → Dashboard React
/admin/aiworker-agents     → Agent Docker image
/admin/aiworker-gitops     → ArgoCD manifests
/aiworker/<project-name>   → Proyectos de usuarios

Cada repo:

• Tiene su propio .gitea/workflows/build.yml
• Buildea a git.fuq.tv/<owner>/<repo>:<tag>
• Deploy independiente

---

🔐 Autenticación en Diferentes Contextos

1. Git Clone/Push (HTTPS)

# Con token en URL (inseguro pero funciona)
git clone https://admin:159a5de2a16d15f33e388b55b1276e431dbca3f3@git.fuq.tv/admin/myrepo.git

# O configurar credential helper
git config --global credential.helper store
git clone https://git.fuq.tv/admin/myrepo.git
# Primera vez pedirá user/password, luego lo guarda

2. Docker Registry

docker login git.fuq.tv -u admin -p 7401126cfb56ab2aebba17755bdc968c20768c27

3. Kubernetes Pulls

Secret ya creado:

# En control-plane y agents
kubectl get secret gitea-registry -n control-plane
kubectl get secret gitea-registry -n agents

Usar en deployment:

imagePullSecrets:
- name: gitea-registry

4. API Calls

Header:

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

5. Webhooks

Secret (para verificar requests):

# Configurar en webhook
"secret": "webhook-secret-aiworker-2026"

# Verificar en backend usando HMAC

---

📦 Build Strategies

Estrategia Actual: Gitea Actions

Ventajas:

• ✅ Sin Docker local necesario
• ✅ Build en cluster (más recursos)
• ✅ Histórico de builds en UI
• ✅ Cacheo de layers

Cómo funciona:

Push → Gitea Actions → Runner Pod (DinD) → Docker build → Push to registry

Configuración:

• Runner: Pod en namespace gitea-actions
• Docker-in-Docker (DinD) para builds
• Volumenes compartidos para cache

Alternativa Futura: ArgoCD Image Updater

Cuando esté configurado:

Push → Build → Registry → ArgoCD detecta → Auto-update K8s → Deploy

---

🎯 Checklist de Feature Completa

• Desarrollo local con bun run dev
• Test manual de endpoints
• Commit con mensaje descriptivo
• Push a Gitea
• Verificar build en Actions (verde ✅)
• Verificar imagen en registry
• Deploy en K8s (manual o ArgoCD)
• Verificar pods running
• Test en producción (api.fuq.tv)
• Verificar logs sin errores

---

🐛 Troubleshooting del Workflow

Build Falla en Actions

# Ver logs del job
https://git.fuq.tv/admin/aiworker-backend/actions/runs/<run-id>

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

# Problemas comunes:
# - Dockerfile error → Fix Dockerfile
# - Dependencias faltantes → Update package.json
# - Registry auth → Verificar REGISTRY_TOKEN secret

Fix: Corregir error, commit, push de nuevo.

Build OK pero K8s no Pulla Imagen

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

# Verificar imagePullSecrets en deployment
kubectl get deployment backend -n control-plane -o yaml | grep imagePullSecrets

# Ver eventos
kubectl describe pod <pod-name> -n control-plane | grep -i pull

Fix: Recrear secret o agregar imagePullSecrets al deployment.

Imagen en Registry pero versión vieja en K8s

# Force pull nueva imagen
kubectl rollout restart deployment/backend -n control-plane

# O delete pod para recrear
kubectl delete pod <pod-name> -n control-plane

Nota: Si usas tag latest, K8s cachea. Mejor usar tags específicos (v1.0.0, main-abc1234).

---

📊 Monitoring del Workflow

CI/CD Health

# Runner status
kubectl get pods -n gitea-actions

# Workflows recientes
open https://git.fuq.tv/admin/aiworker-backend/actions

# Registry usage
open https://git.fuq.tv/admin/-/packages

Deployments

# Backend
kubectl get pods -n control-plane
kubectl logs -f deployment/backend -n control-plane

# Frontend (cuando exista)
kubectl get pods -n control-plane
kubectl logs -f deployment/frontend -n control-plane

---

🎓 Best Practices

1. Commits frecuentes - Push pequeños, builds rápidos
2. Tags semánticos - v1.0.0, v1.1.0 para releases
3. Branch strategy - main (prod), develop (staging), feature/* (features)
4. PR reviews - Siempre review antes de merge
5. Registry cleanup - Eliminar imágenes viejas periódicamente
6. Logs - Siempre verificar logs post-deploy

---

🔗 Referencias

• Guía Gitea completa: GITEA-GUIDE.md
• Container Registry: docs/CONTAINER-REGISTRY.md (puedes eliminar después)
• API Gitea: docs/02-backend/gitea-integration.md (código de ejemplo)
• CI/CD: docs/06-deployment/ci-cd.md

---

✅ Con este workflow, el desarrollo es fluido: código local → push → build automático → deploy → verificar.