nucleoDocs/.claude/hooks/README.md

Gitea Actions Monitor Hook

Este hook monitorea automáticamente tus Gitea Actions después de hacer git push y te notifica cuando terminan.

Configuración

1. Crear un token de acceso en Gitea

1. Ve a: https://gitea.nucleoriofrio.com/user/settings/applications
2. En la sección "Generate New Token":
   • Token Name: claude-code-monitor (o el nombre que prefieras)
   • Select Permissions: Marca read:repository o repo (lectura de repositorio)
3. Click en "Generate Token"
4. IMPORTANTE: Copia el token inmediatamente (solo se muestra una vez)

2. Configurar la variable de entorno

Agrega el token a tu archivo de configuración de shell:

Para Bash (~/.bashrc):

export GITEA_TOKEN='tu_token_aqui'

Para Zsh (~/.zshrc):

export GITEA_TOKEN='tu_token_aqui'

Para Fish (~/.config/fish/config.fish):

set -x GITEA_TOKEN 'tu_token_aqui'

Luego recarga la configuración:

source ~/.bashrc   # o ~/.zshrc o reinicia la terminal

3. Verificar que funciona

Verifica que la variable está configurada:

echo $GITEA_TOKEN

Deberías ver tu token.

Uso

Una vez configurado, el hook se activa automáticamente cuando Claude Code ejecuta git push:

1. Claude ejecuta git push
2. El hook verifica que Actions estén habilitadas
3. El hook se activa automáticamente y comienza a monitorear
4. Claude se congela mientras espera a que termine la Gitea Action (máximo 10 minutos)
5. Puedes presionar Ctrl+C para interrumpir la espera si es necesario
6. Cuando termine, Claude te muestra información detallada:

Ejemplo de action exitosa:

✅ Gitea Action completada: EXITOSO

📋 Detalles:
  • Workflow: build-and-deploy (build-and-deploy.yml)
  • Run #3
  • Evento: push
  • Branch: master
  • Commit: a1b2c3d4
  • Título: Update README: Add Claude Code hooks feature
  • Duración: 5m 23s
  • Iniciado: 2025-10-12T14:30:05Z
  • Finalizado: 2025-10-12T14:35:28Z

🔗 Ver logs completos:
   https://gitea.nucleoriofrio.com/nucleo000/plantillaNuxtAuthentikProxy/actions/runs/123

Si las Actions no están habilitadas:

⚠️ Git push exitoso, pero las Gitea Actions NO están habilitadas en este repositorio.

📝 Para habilitar Actions:
1. Ve a: https://gitea.nucleoriofrio.com/nucleo000/plantillaNuxtAuthentikProxy/settings
2. Busca la sección 'Actions' o 'Workflows'
3. Activa las Actions

Configuración Avanzada

Cambiar el timeout

Edita .claude/settings.local.json y modifica el valor timeout (en segundos):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/monitor-gitea-action.sh",
            "timeout": 300  // 5 minutos en lugar de 10
          }
        ]
      }
    ]
  }
}

Cambiar el intervalo de polling

Edita .claude/hooks/monitor-gitea-action.sh y modifica:

POLL_INTERVAL=10  # Consultar cada 10 segundos (puedes cambiar a 5, 15, 30, etc.)

Troubleshooting

El hook no se activa

1. Verifica que el archivo de configuración es correcto: cat .claude/settings.local.json
2. Reinicia Claude Code para que recargue la configuración
3. Revisa los logs con claude --debug

Error "falta GITEA_TOKEN"

El token no está configurado. Sigue los pasos de configuración arriba.

Timeout: La action todavía está corriendo

La action tardó más de 10 minutos. Puedes:

• Aumentar el timeout en la configuración
• Verificar el estado manualmente en Gitea
• Optimizar tu Gitea Action para que sea más rápida

El script no puede conectarse a la API

1. Verifica que puedes acceder a Gitea: curl https://gitea.nucleoriofrio.com
2. Verifica que el token es válido:

   curl -H "Authorization: token $GITEA_TOKEN" \
     https://gitea.nucleoriofrio.com/api/v1/repos/nucleo000/plantillaNuxtAuthentikProxy/actions/tasks?limit=1
   

Desactivar el hook

Si quieres desactivar temporalmente el hook, comenta o elimina la sección hooks en .claude/settings.local.json.