CI Soberano — Forgejo, runners propios y deploy a Vercel

1 Qué es y por qué

Agent Squad migró su git + CI de GitHub Actions a Forgejo self-hosted para eliminar la dependencia de GitHub.

• Gatillo: el billing de GitHub Actions agotado bloquea Actions a nivel cuenta (hosted y self-hosted: el runner sano recibía 0 jobs). Se eligió soberanía en vez de subir el límite de gasto.
• Decisión: Forgejo (no Gitea) por gobernanza nonprofit + GPL.
• Alcance: código + CI soberanos; Vercel sigue hosteando la web. El deploy pasó de gitSource: github a vercel deploy --prebuilt disparado desde el CI.
• Reversible: Forgejo corrió en paralelo a GitHub hasta el cutover; GitHub quedó fuera del path de deploy.

2 Infraestructura

Servidor de Forgejo — VPS «truo»

• Ubuntu 26.04 KVM, 4 vCPU / 8 GB (proveedor truo.co).
• SSH: password login DESACTIVADO; solo clave dedicada (ver §6). ufw solo 22 entrante.
• Forgejo v16.0.3 en Docker (/opt/forgejo, base SQLite, docker run sin compose).
• Público en https://git.digitalhubassist.ai vía Cloudflare Tunnel (cloudflared systemd): sin puertos abiertos, IP del servidor oculta, satisface Cloudflare Full (Strict).
• act_runner = forgejo-runner (systemd, User=runner, modo mixto host/docker).

Box de runners (Hetzner)

• Hetzner 8 vCPU / 16 GB. Corre un segundo runner en ~/forgejo-runner-hetzner/ (systemd forgejo-runner-hetzner.service, User=clawd).
• Es también el host de operación: desde acá se orquesta y monitorea el CI.

3 Runners y paralelización

• Paralelización: los 6 shards de Playwright (fast 1-2 + 3D 1-4) se reparten entre truo y Hetzner → la suite baja de ~35 min a ~18 min.
• Modo mixto por label: la mayoría de jobs corren en host-mode; los jobs Playwright usan el label pw → docker-mode con imagen custom local/playwright-bun:v1.60.0 (= mcr.microsoft.com/playwright:v1.60.0-noble + unzip), porque Playwright 1.60 no soporta chromium en el Ubuntu 26.04 del host.

4 Workflow · .github/workflows/ci.yml

Triggers (on:)

• push → branches: [main]
• pull_request → branches: [main]
• schedule (nightly ~6 UTC — red de seguridad del filtrado por paths)
• workflow_dispatch (manual)

Job de gating: cambios («Qué tocó este push»)

Filtro de paths que produce outputs booleanos que gatean el resto de los jobs:

Inocuos (no corren shards): docs/, _design/, experiments/, substrate-infra/, *.md, apps/api/, etc.

Jobs y dependencias (DAG)

• Postgres de test: contenedor persistente substrate-test-pg (timescaledb-ha:pg16) en 127.0.0.1:5432 (NO localhost → resuelve a ::1). Migraciones hacen dropdb/createdb por corrida.
• cache OFF (cache.enabled: false): el cache server no era alcanzable desde el contenedor y colgaba ~4.5 min/corrida.
• Actions de GitHub (uses: actions/*) se resuelven desde github.com (DEFAULT_ACTIONS_URL=github).

5 Pipeline de deploy (Vercel --prebuilt)

El job deploy corre en todo push a main que pase el gate (no está gateado por cambios.web):

if: always() && ref==refs/heads/main && event=='push'
    && cambios==success && check==success && e2e-criticos==success
    && (web-test  == success || skipped)
    && (api-test  == success || skipped)
    && (e2e-fast  == success || skipped)
    && (e2e-3d    == success || skipped)

Pasos del deploy (escalonado, con red de seguridad)

• 1. Build + deploy staged: vercel pull → vercel build --prod → vercel deploy --prebuilt --prod --skip-domain --env APP_COMMIT_SHA=$SHA. --skip-domain deja el dominio custom intacto (sube un deployment de prod sin promoverlo).
• 2. Smoke sobre la URL inmutable (pre-promote): valida commit en /api/version + rutas /, /demo, /welcome. Un rojo acá no toca producción.
• 3. Freshness + promote: promueve (mueve el alias del dominio) solo si el $SHA es HEAD de main o ancestro de HEAD (git merge-base --is-ancestor). Evita el livelock de ráfaga.
• 4. Smoke contra el dominio + rollback si falla.

Detalles de operación del CLI

• CLI pinneado a bunx vercel@59.5.0. Correr desde la raíz del repo (rootDirectory = apps/web).
• vc <timeout> <retry|noretry> …: wrapper con timeout --signal=KILL + reintento acotado (solo ante timeout 124/137). < /dev/null para evitar SIGTTIN.
• APP_COMMIT_SHA se inyecta por --env y /api/version lo lee en runtime (VERCEL_* es prefijo reservado).

6 Dónde viven las variables, tokens y secretos

Solo referencias de ubicación — ningún valor se transcribe. Para leer un valor, abrir el archivo en el host correspondiente.

En el box de operación (Hetzner)

En el servidor de Forgejo (truo)

Secrets del CI (definidos en Forgejo, repo aguirrerjg/agent-squad-app)

Referenciados en ci.yml como ${{ secrets.* }} — no se transcriben:

• VERCEL_TOKEN
• VERCEL_PROJECT_ID
• VERCEL_TEAM_ID (== org id)

7 Operación y monitoreo

Acceso

• truo: ssh truo (alias en ~/.ssh/config → clave truo_runner, user root).
• Forgejo API: https://git.digitalhubassist.ai/api/v1/repos/aguirrerjg/agent-squad-app/… con Authorization: token <read-token>. Usar curl (urllib da 403 por Cloudflare UA).

Endpoints útiles

• GET …/actions/tasks?limit=N — estado de jobs.
• GET …/branches/main — HEAD de main.
• POST …/actions/runs/{index}/cancel → 204 — cancela un run (usa el index = run_number). Rerun NO existe por API (404): relanzar es desde la UI web o un nuevo push.
• Web servida: GET https://app.agentsquadai.com/api/version → { commit }.

status en la DB (action_run / _job / _task)

Logs reales del runner (la API sirve logs stale)

/opt/forgejo/data/gitea/actions_log/<owner>/<repo>/<xx>/<taskid>.log.zst (zstd; zstd -dc). El log_filename sale de SELECT log_filename FROM action_task WHERE id=<taskid>. Marcadores: ⭐ Run, 🏁 Job failed, ⚙️ RUN exit status N (124=timeout TERM, 137=SIGKILL).

8 Gotchas y lecciones

• Auto-deploy exige CI verde de origin/main: el gate del auto-deploy-api.sh chequea GET …/commits/{sha}/status; skipped=verde, unknown→BLOCKED. Fail-closed.
• Contención de Postgres (pgvectorscale/TimescaleDB): substrate-test-pg NO tolera construir una 2ª base en el mismo cluster (el worker de TS por base cuelga CREATE DATABASE … TEMPLATE). Correr la mordida RLS contra la 1ª base.
• SIGTTIN: un proceso que lee stdin sin TTY se detiene (state T), y timeout también → usar < /dev/null.
• Livelock de deploy (resuelto): con HEAD == SHA cada deploy en ráfaga salía verde sin promover; se arregló promoviendo por ancestría.
• El deploy corre solo en truo (runs-on: self-hosted): durante ráfagas de PRs, los deploys de main encolan detrás de los shards.
• Rerun no existe por API; un "reset" manual por DB no relanza (Forgejo tiene su propia máquina de estados) — solo sirve para dejar runs en terminal limpio.