CI/CD de agentes de IA con DOCKUP_TOKEN

El CI/CD de agentes de IA solo funciona correctamente cuando la autenticación y el despliegue se comportan como deben sin que haya una persona frente al terminal. El inicio de sesión mediante navegador, los códigos de un solo uso copiados manualmente y los mensajes de estado únicamente en lenguaje natural son incompatibles con un runner desatendido. Dockup admite el flujo no interactivo mediante DOCKUP_TOKEN, JSON estructurado y comandos de despliegue que devuelven un código de salida de fallo real.

Esta guía define un contrato de pipeline que pueden utilizar Claude Code, Codex, un script de shell o un trabajo de CI convencional. Se aplican las mismas reglas: inyectar el token en tiempo de ejecución, verificar la identidad, descubrir o especificar el destino exacto, esperar un resultado terminal y conservar los diagnósticos en caso de fallo.

¿Por qué el CI/CD de agentes de IA necesita autenticación no interactiva?

El comando interactivo dockup login abre una página de autenticación y espera un token. Esto es adecuado en el equipo de trabajo de un desarrollador, pero un runner en un contenedor puede no tener navegador, un directorio de inicio persistente ni una persona disponible para pegar nada.

DOCKUP_TOKEN resuelve ese límite:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

La variable de entorno tiene prioridad sobre ~/.dockup/config.json. whoami informa de tokenSource, por lo que el pipeline puede demostrar que está utilizando la credencial inyectada prevista y no un archivo de configuración antiguo que haya quedado en un runner autohospedado.

No ejecutes dockup login -t "$DOCKUP_TOKEN" en CI salvo que exista un motivo específico para conservar un archivo de configuración. Proporcionar directamente la variable de entorno mantiene la credencial limitada al proceso y evita escribirla en el directorio de inicio del runner.

El pipeline nunca debe mostrar el token. Desactiva el trazado del shell alrededor de los comandos que contengan secretos, evita imprimir el entorno completo y utiliza la función de secretos enmascarados de la plataforma de CI.

¿Cómo se debe almacenar y limitar el alcance de DOCKUP_TOKEN?

Almacena el token como un secreto cifrado del repositorio, del entorno o de la organización. Da preferencia a un secreto de nivel de entorno para producción, ya que puede combinarse con restricciones de rama y aprobaciones manuales proporcionadas por la plataforma de CI.

Una política segura de tokens responde a cinco preguntas:

Pregunta	Respuesta recomendada
¿Dónde se almacena el token?	Almacén de secretos cifrados de CI
¿Cuándo queda expuesto?	Solo en el trabajo de despliegue
¿Qué ramas pueden utilizarlo?	Ramas de producción protegidas
¿Quién puede modificar el workflow?	Maintainers revisados
¿Cómo se revisa su uso?	Registro de auditoría de Dockup y historial del trabajo de CI

Dockup también admite API keys con permisos. Enumera los nombres de permisos disponibles antes de crear una clave con un alcance limitado:

dockup keys permissions --json

Elige únicamente los nombres de permisos exactos que devuelva la plataforma y, después, crea la clave mediante el workflow de API keys con permisos. Captura la clave generada de forma segura durante su creación y guárdala inmediatamente; no la incluyas en una incidencia, pull request ni transcripción de un agente. Un trabajo de despliegue no debería heredar una administración amplia de la cuenta simplemente porque el token de un desarrollador ya disponga de ella.

El artículo Protecciones de producción para agentes de IA ofrece una escala de permisos más amplia.

¿Cómo se crea un pipeline de despliegue que espere al resultado real?

Instala la CLI en el trabajo, verifica la identidad y despliega con --wait:

name: production-deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DOCKUP_TOKEN: ${{ secrets.DOCKUP_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Dockup CLI
        run: npm install -g dockup-cli

      - name: Verify Dockup identity
        run: dockup whoami --json

      - name: Deploy and wait
        run: dockup deploy production/api --wait --json

La parte importante no es el proveedor de CI, sino el contrato del comando. dockup deploy ... --wait --json sale con 0 únicamente cuando el despliegue alcanza el estado correcto. El tiempo de espera predeterminado es de 900 segundos. Una compilación fallida devuelve una salida distinta de cero con deploy_failed; una operación que no llega a un estado terminal cuando se agota el tiempo devuelve deploy_timeout.

Como el proceso sale con un valor distinto de cero, el runner marca el paso y el trabajo como fallidos. No es necesario analizar los logs.

En un repositorio vinculado que deba hacer push de su rama actual y desplegarla, dockup push --json espera de forma predeterminada. En un trabajo de CI que ya ha recibido un evento de push de Git, un dockup deploy <target> explícito suele ser más claro, ya que evita hacer push desde el runner.

¿Cómo debe capturar un pipeline los logs y los códigos de error?

Conserva el resultado JSON del despliegue como artifact o salida del trabajo, pero evita que una redirección oculte el estado de salida. Un patrón de shell puede capturar ambos:

set +e
dockup deploy production/api --wait --json > deploy-result.json
status=$?
set -e

if [ "$status" -ne 0 ]; then
  dockup logs production/api --build --json > build-logs.json || true
  cat deploy-result.json
  exit "$status"
fi

dockup status production/api --json

El pipeline termina con el estado original del despliegue. Los logs de compilación solo se recopilan después de un fallo. Los logs de runtime deben recopilarse cuando la imagen se ha compilado, pero la aplicación se bloquea posteriormente:

dockup logs production/api --json

Para consultar en directo el progreso de la compilación, el modo follow emite NDJSON:

dockup logs production/api --build -f --json

El flujo termina cuando lo hace el despliegue y el fallo sigue produciendo un resultado de proceso distinto de cero. La secuencia detallada de diagnóstico se explica en depuración de logs de compilación y runtime.

Un pipeline debe decidir en función de los códigos, no de fragmentos de mensajes:

Código	Respuesta del pipeline
not_logged_in	Fallar inmediatamente; la inyección del secreto no funciona
no_target	Fallar; la configuración del destino no es válida
deploy_trigger_failed	Fallar antes de esperar; inspeccionar el error devuelto
deploy_failed	Subir los logs de compilación y fallar
deploy_timeout	Marcar como incierto; inspeccionar el estado antes de reintentar
needs_confirm	Detenerse; un paso destructivo no tiene aprobación

¿Cómo puede participar un agente sin debilitar la seguridad de CI?

Un agente puede preparar código, actualizar un workflow revisado, interpretar JSON y resumir una compilación fallida. No necesita acceso sin restricciones al token de producción en todas las sesiones de programación.

Separa los roles:

1. Agente de desarrollo: edita el código y ejecuta las pruebas localmente.
2. Proceso de revisión: valida los cambios en la configuración del despliegue.
3. Runner de CI: recibe DOCKUP_TOKEN únicamente después del trigger aprobado.
4. Dockup: ejecuta el despliegue y registra los eventos de auditoría.
5. Agente u operador: interpreta el resultado y propone la recuperación.

Esta disposición evita que una prompt injection en una tarea no relacionada obtenga credenciales de producción. El agente puede seguir entendiendo el pipeline porque los comandos y el JSON esperado están confirmados en el repositorio, mientras que el valor secreto permanece fuera de él.

Para despliegues ejecutados directamente por un agente, inyecta el token en el proceso específico de Claude Code o Codex e instala la skill incluida:

npm install -g dockup-cli
dockup skill install
dockup whoami --json

La skill indica a ambos agentes que utilicen autenticación no interactiva, JSON, descubrimiento del destino exacto, espera hasta el estado terminal y gates de confirmación.

¿Qué hace que el CI/CD de agentes de IA sea repetible y auditable?

La repetibilidad comienza con un destino explícito. Almacena production/api como variable protegida del pipeline o como literal revisado, no como un nombre que el agente derive en tiempo de ejecución. Valida la cuenta antes de realizar la primera escritura.

La idempotencia requiere un tratamiento diferente según la operación:

• Leer la identidad, el estado, los logs y el historial se puede repetir de forma segura.
• La creación de servicios debe comenzar con el descubrimiento del destino para que los reintentos no creen duplicados.
• Volver a desplegar crea otro evento de producción y debe quedar registrado.
• Los cambios de entorno son mutaciones y requieren un nuevo despliegue.
• La destrucción y la limpieza no deben ser objetivos de reintentos automáticos.

Después del despliegue, recopila evidencias de la plataforma:

dockup status production/api --json
dockup uptime production/api --hours 24 --json
dockup audit --writes --json

El uptime se mide cada minuto e incluye el tiempo de respuesta medio y p95. La salida de auditoría relaciona la mutación de CI con la revisión posterior. El consumo de CPU, RAM y disco también se mide por minuto frente al saldo de la cuenta; el plan Pro recomendado cuesta 20 $ al mes e incluye 20 $ de crédito de uso.

Un registro completo del pipeline incluye el commit de Git, el destino de Dockup, el ID del despliegue, las marcas de tiempo de inicio y finalización, el código de salida, el estado terminal y los enlaces a los artifacts de compilación. Esto hace que una versión de CI/CD de agentes de IA sea reproducible incluso cuando la sesión original del agente ya no existe.

La referencia de Dockup CLI debe considerarse la autoridad sobre los comandos. Para crear el repositorio antes de habilitar CI, sigue Del repositorio de Git a producción.

Controla la concurrencia y la promoción entre entornos

Dos pipelines correctos aún pueden crear una versión insegura si se ejecutan simultáneamente sobre el mismo destino. Utiliza los controles de concurrencia de la plataforma de CI para que un trabajo de producción más reciente espere al anterior o lo reemplace de forma deliberada. Dockup informará fielmente de cada despliegue, pero el workflow del repositorio debe decidir cómo se ordenan los commits simultáneos.

Promociona el mismo commit revisado entre entornos en lugar de volver a compilar un estado local no registrado. Un trabajo de staging puede desplegar staging/api, ejecutar comprobaciones de la aplicación y permitir después que un trabajo de producción protegido despliegue production/api. Mantén separados los tokens y los destinos para que un agente de staging no pueda cruzar el límite accidentalmente.

Define una política de reintentos para los timeouts

deploy_timeout no significa que haya fallado ni que haya tenido éxito. Significa que la operación seguía ejecutándose cuando terminó la espera de 900 segundos. Antes de reintentar, inspecciona:

dockup status production/api --json
dockup deployments production/api -n 5 --json

Si el despliegue original alcanza posteriormente el estado correcto, un reintento a ciegas crearía otra versión. Si ha fallado, recopila el log de compilación. Si sigue sin llegar a un estado terminal y la compilación es legítimamente larga, vuelve a observarla con un timeout documentado mayor en lugar de crear un segundo despliegue.

Esta distinción evita que el CI/CD de agentes de IA convierta la incertidumbre de red o de tiempos en cambios duplicados en producción.

Registra la identidad del despliegue

Incluye en el resumen de CI la identidad de la cuenta de Dockup, el destino, el SHA del commit, el ID del despliegue y el estado terminal. Este pequeño registro permite que un operador posterior relacione la ejecución del pipeline con los eventos de auditoría de Dockup sin exponer el token.

Lleva el workflow a producción

Instala la CLI en el runner, verifica la identidad inyectada y convierte el estado de salida terminal —no una línea de log que parezca indicar éxito— en el gate del pipeline.

npm install -g dockup-cli
dockup skill install

El primer comando instala la CLI. El segundo instala la skill de Dockup correspondiente para Claude Code y Codex. Empieza gratis en app.dockup.ai.

Preguntas frecuentes

¿Qué es DOCKUP_TOKEN?

DOCKUP_TOKEN es el mecanismo de autenticación mediante variables de entorno para sesiones de Dockup CLI que no pueden completar el inicio de sesión interactivo mediante navegador, incluidos runners de CI, contenedores y agentes de IA.

¿DOCKUP_TOKEN sustituye a un archivo de configuración local de Dockup?

Sí. El token del entorno tiene prioridad y dockup whoami --json informa del origen del token activo.

¿Cómo sabe un trabajo de CI que ha fallado un despliegue de Dockup?

Ejecuta dockup deploy con --wait y --json. El comando termina con un valor distinto de cero y un código de fallo estructurado cuando el despliegue falla o agota el tiempo de espera.

¿Debe un workflow de CI mostrar el token de despliegue para depurar?

No. Guárdalo en el almacén de secretos de CI, evita el trazado del shell y los volcados del entorno, y expónlo únicamente al paso de despliegue.

¿Pueden Claude Code o Codex utilizar el mismo mecanismo de autenticación de CI?

Sí. Ambos pueden utilizar DOCKUP_TOKEN y la skill de Dockup incluida, que enseña las mismas reglas de JSON, descubrimiento del destino, espera y confirmación.