Día 14: el equipo deja de ejecutar Claude Code. El pipeline empieza a ejecutarlo por ellos.

Módulo 9 · Capstone · Lección 3 de 4

Al terminar esta lección podrás conectar Claude Code a un workflow de GitHub Actions, configurar la autenticación correctamente para un entorno no interactivo y diagnosticar el problema de proxy que hace tropezar a la mayoría de los equipos en esta etapa.

Dónde estás

Dos semanas después, el equipo hace la pregunta que esperabas

Pasar a CI es una buena señal, no una complicación.

Para el Día 14, la mayoría de las cohortes piloto han usado Claude Code de forma interactiva el tiempo suficiente para confiar en lo que hace. Cuando empiezan a preguntar si pueden automatizarlo, integrarlo en su proceso de pull requests o ejecutar comprobaciones de forma headless, la curva de adopción funciona como debe. El modelo de interacción cambia aquí: en lugar de que un desarrollador le escriba prompts a Claude Code, un workflow lo dispara. Ese cambio es pequeño en términos de configuración y significativo en la forma en que el equipo piensa sobre la herramienta. Tu trabajo es dejar bien el cableado, resolver la autenticación a la primera y anticipar el único problema de proxy que aparece en casi todos los entornos de CI empresariales.

El pipeline

Así se ve en realidad una integración con GitHub Actions

Son cuatro pasos. Las decisiones interesantes están en los pasos dos y tres.

1. Añade el archivo de workflow. Un YAML estándar en .github/workflows/ que se dispara en pull request o push. Claude Code se ejecuta como un paso dentro de un job existente, no como un runner especial propio. Mantenlo cerca del resto de la configuración de CI del equipo para que no parezca un elemento ajeno.

2. Guarda la clave de API como secreto del repositorio. La clave va en los secretos de GitHub Actions, expuesta al paso como ANTHROPIC_API_KEY. Aquí también decides si la clave es personal o una clave de servicio compartida: conviene confirmarlo con el equipo de seguridad del cliente antes de llevar el workflow a producción. Nunca imprimas la clave en los logs.

3. Configura la variable del proxy si hace falta. Si el cliente enruta Claude Code a través de su proxy empresarial (lo que hace la mayoría), ANTHROPIC_BASE_URL debe configurarse explícitamente en el workflow. No se traslada desde la configuración local ni desde el CLAUDE.md del desarrollador. Es el paso que más se omite y el que causa los fallos más confusos.

4. Invoca con --print y restringe las herramientas. El flag --print ejecuta Claude Code de forma no interactiva y escribe la salida en stdout. En CI casi siempre quieres también --allowedTools, para acotar lo que Claude puede hacer a exactamente lo que necesita el workflow. Un pipeline que puede leer archivos y ejecutar tests no necesita acceso de escritura a todo el sistema de archivos.

flowchart LR
    A["Pull request o push"] --> B["Job existente del workflow"]
    B --> C["Paso de Claude Code (--print, --allowedTools)"]
    C --> D["Salida escrita en stdout"]

Autenticación en CI

Cuatro cosas que conviene resolver antes de la primera ejecución

La autenticación en un entorno no interactivo es lo bastante distinta de la local como para repasarla con calma. Cada punto es una decisión distinta, no un elemento de checklist.

1. Tipo de clave de API. ¿Es una clave personal de desarrollador o una clave de cuenta de servicio dedicada? Las claves de cuenta de servicio son la opción correcta para entornos de CI compartidos: tienen rotación controlada y no se rompen cuando cambia el acceso de un desarrollador.

2. Almacenamiento del secreto. Las claves van en los secretos de GitHub Actions, no codificadas en el YAML del workflow ni confirmadas en ningún lugar del repositorio. Si el cliente usa un gestor de secretos (Vault, AWS Secrets Manager), confirma si el runner tiene acceso antes de configurar el workflow.

3. Enrutamiento por proxy. ANTHROPIC_BASE_URL debe configurarse explícitamente en el entorno de CI. En despliegues empresariales con un gateway de Claude Code, la URL del gateway va aquí. Sin ella, el runner hace una llamada directa a la API de Anthropic, que puede estar bloqueada en la capa de red.

4. Permisos de herramientas. Usa --allowedTools para acotar exactamente lo que Claude puede hacer en el pipeline. Normalmente basta con acceso de lectura, al runner de tests y al linter. Los permisos amplios en un contexto no interactivo son más difíciles de auditar y de explicar al equipo de seguridad del cliente.

El fallo habitual

El problema de proxy no parece un problema de proxy

La mayoría de los despliegues empresariales de Claude Code enrutan el tráfico a través de un gateway. Esa URL del gateway vive en la configuración local. Y se queda ahí.

Lo que realmente se observa

El GitHub Action falla con un timeout de conexión o un 403. La configuración local del desarrollador funciona perfectamente. La clave de API está confirmada como correcta. La causa más probable es que ANTHROPIC_BASE_URL nunca se configuró en el workflow. El runner intenta llegar directamente a la API de Anthropic, y la política de red empresarial lo bloquea. Solución: añade ANTHROPIC_BASE_URL como secreto de Actions y referencíala en el paso del workflow. Si el cliente usa un gateway de Claude Code, ese es el valor. Confírmalo con quien administra la configuración del despliegue: normalmente está en el CLAUDE.md o en la documentación de configuración del entorno de la lección de Arquitectura de despliegue.

flowchart TD
    A["Runner de CI"] --> B{"¿ANTHROPIC_BASE_URL configurada en el workflow?"}
    B -->|"Sí"| C["El runner llega al gateway del cliente"]
    B -->|"No"| D["El runner intenta llegar directo a la API de Anthropic"]
    D --> E["La política de red puede bloquearlo: timeout o 403"]

Comprueba tu comprensión

Día 14, primera ejecución en CI. El job falla.

Escenario · Día 14

El workflow del equipo de GitHub Actions se dispara en un pull request. El paso que llama a Claude Code falla con un error de conexión tras 30 segundos. El desarrollador confirma que el secreto ANTHROPIC_API_KEY está configurado. Su sesión local de Claude Code funciona bien con el mismo código base. ¿Qué compruebas primero?

• A · Rotar la clave de API. La clave pudo haber sido invalidada. Genera una nueva y actualiza el secreto.
• B · Revisar si ANTHROPIC_BASE_URL está en el workflow. Local funciona, CI falla. La diferencia más probable es el enrutamiento por proxy. Confirma que la URL del gateway esté configurada como secreto y referenciada en el paso.
• C · Cambiar a modo verbose y volver a ejecutar. Añade logs de depuración al paso del workflow para obtener más información antes de diagnosticar.
• D · Revisar la política de red saliente del runner. El firewall empresarial puede estar bloqueando la conexión. Trabaja con TI para confirmar que el runner puede alcanzar el endpoint de la API.

Ver respuesta

B es la respuesta correcta, pero conviene entender por qué D no lo es. Local funciona y CI falla. La clave de API está confirmada. Esa asimetría casi siempre apunta a la configuración del entorno: concretamente, algo que está presente en la configuración local y que no se trasladó al workflow. ANTHROPIC_BASE_URL es el culpable más habitual: Claude Code local la toma del entorno del desarrollador o del CLAUDE.md, pero el runner de CI no tiene equivalente. El runner entonces intenta una llamada directa a la API de Anthropic, que la política de red empresarial suele bloquear. Por eso parece un problema de red, porque en el router lo es. Pero la causa raíz es una variable de entorno que falta, no una excepción en el firewall. Primero corrige el paso del workflow. Si la URL del gateway está confirmada como correcta y aun así falla, entonces la pregunta sobre la política de red se vuelve relevante.

Ideas clave

El pipeline está en marcha. La activación está casi terminada.

• Claude Code se integra en GitHub Actions como un paso dentro de un job existente, invocado con --print y con --allowedTools para acotar lo que puede hacer.
• La clave de API va en los secretos del repositorio como ANTHROPIC_API_KEY. Nunca se imprime en los logs ni se codifica en el YAML.
• ANTHROPIC_BASE_URL debe configurarse explícitamente en el workflow: no se traslada desde la configuración local ni desde el CLAUDE.md del desarrollador.
• Si el job falla con un error de conexión mientras la sesión local funciona, la causa más probable es esa variable que falta, no una excepción del firewall.

La última lección cubre los modos de fallo que aparecen en las semanas 3 y 4, cómo leerlos y cómo entregar un plan de activación limpio que el cliente pueda ejecutar de forma independiente.

Siguiente: Playbook de troubleshooting y plan de activación