Deployment de Codex: flujo de trabajo completo con Dockup

Un deployment de Codex debería terminar con evidencias, no con suposiciones. El reto práctico no consiste en pedirle a Codex que ejecute un comando de deploy, sino en proporcionarle una interfaz que identifique el target exacto, espere a un estado terminal, devuelva códigos de salida reales y exponga los detalles del fallo sin necesidad de un navegador.

Dockup es la capa de deployment de este flujo de trabajo. Su CLI proporciona a Codex JSON estructurado en todos los comandos compatibles, y su skill incluida enseña al agente a autenticarse, descubrir servicios, hacer deploy, diagnosticar problemas y detenerse antes de ejecutar operaciones destructivas.

¿Cómo se instala la skill de Codex CLI?

Instala la CLI globalmente y ejecuta después el instalador de la skill. Este escribe la skill canónica y crea enlaces a ella desde Claude Code y Codex:

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

La skill canónica se encuentra en ~/.agents/skills/dockup/ y está enlazada mediante symlink desde ~/.codex/skills/. Se incluye dentro de dockup-cli, por lo que una actualización normal modifica el ejecutable y sus instrucciones al mismo tiempo:

dockup update

Esta relación entre versiones es importante cuando la superficie de comandos es amplia. Un agente nunca debería ejecutar un flag que recuerda solo porque aparecía en un prompt antiguo. Codex debe usar la skill incluida y la referencia actual de Dockup CLI como fuente de autoridad para los comandos.

Para conocer los motivos de diseño de las skills, consulta agent skills vs MCP.

¿Cómo se autentica Codex sin un terminal interactivo?

Es posible que un sandbox o un job de CI no pueda completar un login basado en navegador. Define un token en el entorno del proceso:

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

DOCKUP_TOKEN tiene prioridad sobre el archivo de configuración local. La respuesta de whoami indica si la credencial activa procede del entorno o de la configuración, lo que ayuda a Codex a diagnosticar el caso habitual en el que coexisten un token local obsoleto y un token de CI.

Trata el token como un secret de infraestructura. No lo incluyas en AGENTS.md, SKILL.md, el control de versiones, ejemplos de comandos guardados en el repositorio ni en el transcript final del agente. En CI, utiliza el almacén de secrets cifrado de la plataforma y expón el valor únicamente al paso de deployment. El patrón no interactivo completo se detalla en CI/CD con DOCKUP_TOKEN.

Antes de conceder a Codex permisos de escritura, define su ámbito de permisos. Un alcance inicial razonable incluye el descubrimiento de servicios, el deployment, la lectura de logs y las comprobaciones de estado. El borrado de bases de datos, la destrucción de servicios, los cambios de equipo y la limpieza de configuración deberían seguir requiriendo aprobación.

¿Cómo encuentra o crea Codex el servicio correcto?

Haz que el descubrimiento sea la primera operación. No le pidas a Codex que convierta “Payments API” en un slug inventado:

dockup services --json

Cada resultado incluye un target exacto con el formato project/service. Codex debe copiar ese valor en los comandos posteriores y devolverlo en su resumen.

Cuando no existe ningún servicio, créalo desde Git:

dockup create payments-api \
  --repo https://github.com/acme/payments-api \
  --project production \
  --branch main \
  --deploy \
  --wait \
  --link \
  --json

El comando crea el servicio, hace el deploy, espera hasta que el deployment se resuelve y escribe un enlace .dockup en el directorio de trabajo. Si hay un Dockerfile, se utiliza; de lo contrario, Nixpacks realiza la detección automática del build.

Cuando Codex pierde el estado de la sesión o se vuelve a ejecutar un flujo después de una interrupción de red, debe redescubrir los servicios e inspeccionar el target exacto antes de modificar nada. Si el target ya existe, debe continuar desde su estado y su historial de deployments en lugar de emitir otra solicitud de creación.

La secuencia completa, empezando por el repositorio, está disponible en Del repositorio Git a producción.

¿Cómo debe preparar Codex la configuración antes del deployment?

Pide a Codex que inspeccione los metadatos actuales del servicio antes de modificarlos:

dockup info production/payments-api --json
dockup env list -s production/payments-api --json

La respuesta del entorno incluye las claves y los indicadores isSecret, mientras que los valores secretos permanecen ocultos. Codex puede añadir variables normales y secrets por separado:

dockup env set NODE_ENV=production \
  -s production/payments-api \
  --json

dockup env set STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  --secret \
  -s production/payments-api \
  --json

No incluyas nunca un secret de producción en dockup.yaml; el manifest es adecuado para configuración normal revisable, no para credenciales. Las variables secret existentes no se sobrescriben ni se eliminan mediante el flujo de trabajo de config-as-code.

Configura el puerto de escucha del servicio y el readiness check cuando los conozcas:

dockup set production/payments-api --port 3000 --json
dockup health production/payments-api \
  --path /health \
  --interval 5 \
  --retries 5 \
  --json

Un readiness gate hace que la verificación en producción sea significativa. La plataforma realiza un deployment blue-green y dirige el tráfico únicamente después de que la nueva versión supera el gate.

¿Cómo confirma la verificación en producción el estado terminal?

Para un servicio existente, utiliza un solo comando:

dockup deploy production/payments-api \
  --wait \
  --timeout 900 \
  --json

El timeout explícito coincide con el valor predeterminado de 900 segundos y hace visible la intención del flujo de trabajo. El código de salida 0 significa que el deployment se completó correctamente. Un resultado distinto de cero con deploy_failed indica que el build o el deploy fallaron. deploy_timeout significa que la operación todavía no había alcanzado un estado terminal cuando terminó el periodo de espera.

La lógica de branching correcta de Codex debe basarse en el estado del proceso:

Resultado	Acción de Codex
Exit 0, status:"success"	Continuar con la verificación de health, uptime y seguridad
deploy_failed	Leer los build logs e identificar el primer error accionable
deploy_timeout	Informar de la incertidumbre; inspeccionar el estado o reintentar con un timeout justificado
not_logged_in	Detenerse y solicitar un token válido
needs_confirm	Detenerse y solicitar aprobación humana

Después de un deployment de Codex correcto, recopila evidencias observables:

dockup status production/payments-api --json
dockup uptime production/payments-api --hours 24 --json
dockup security production/payments-api --json

Las comprobaciones de uptime se ejecutan cada minuto e incluyen estadísticas del tiempo de respuesta, como p95. Los resultados de seguridad incluyen CVE de la imagen y comprobaciones de configuración. Estas señales no demuestran que la aplicación funcione correctamente, por lo que Codex también debería ejecutar los smoke tests propios del repositorio cuando estén disponibles.

¿Cómo debe diagnosticar Codex una release fallida y recuperarse?

Los errores de build y los errores de runtime requieren logs diferentes. Utiliza el último build output cuando el deployment nunca haya llegado a un contenedor ejecutable:

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

Utiliza los logs de runtime cuando la imagen se haya construido, pero la aplicación se bloquee, se vincule al puerto incorrecto o falle después del arranque:

dockup logs production/payments-api --json

El modo follow resulta útil durante un build largo:

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

En modo JSON, el output de follow es NDJSON, lo que permite a Codex procesar cada batch a medida que llega. El stream termina cuando el deployment alcanza un estado terminal y conserva el código de salida real del fallo.

La recuperación empieza por el historial, no por un target de rollback elegido al azar:

dockup deployments production/payments-api -n 20 --json
dockup rollback <deploymentId> production/payments-api --json

Codex debe identificar un deployment que se sepa que ha sido correcto, indicar el ID seleccionado y conservar las evidencias del fallo antes de volver a ejecutarlo. Nunca debe elegir “el segundo elemento” sin verificar el estado y las marcas de tiempo.

Un informe final útil tiene siete campos: target, branch o commit, ID del deployment, código de salida, estado terminal, URL de producción y acciones posteriores. Este formato permite que cada deployment de Codex sea revisado por una persona o por un paso posterior de automatización.

Un script compacto de verificación

Este patrón de shell mantiene el deployment y el diagnóstico en un único flujo de control transparente:

if dockup deploy production/payments-api --wait --json > deploy-result.json; then
  dockup status production/payments-api --json
  dockup uptime production/payments-api --hours 24 --json
else
  dockup logs production/payments-api --build --json
  exit 1
fi

El script no busca con grep una frase de éxito. Confía en el código de salida de la CLI, conserva el JSON del deployment y hace fallar el job que lo invoca cuando producción no alcanza un estado correcto.

Haz que los reintentos sean observables, no invisibles

Las sesiones del agente pueden interrumpirse después de que una operación haya comenzado, pero antes de que el resultado llegue al transcript. La siguiente ejecución de Codex no debería repetir a ciegas todas las mutaciones. Debe redescubrir el servicio, inspeccionar el deployment más reciente y determinar si la operación anterior alcanzó un estado terminal.

Un runbook de deployment de Codex debe clasificar los comandos como seguros de repetir, seguros solo después de una inspección o sujetos a aprobación. Las lecturas son seguras de repetir. La creación de servicios requiere realizar primero el descubrimiento. Un nuevo deploy es un nuevo evento de producción y debe registrarse como tal. La limpieza y cualquier otra operación destructiva siguen siendo decisiones humanas.

Separa la verificación de la plataforma de la verificación de la aplicación

Dockup puede demostrar que un build se completó, que el contenedor estuvo listo y que las probes de nivel minuto observan el servicio público. Codex debe ejecutar igualmente comprobaciones específicas de la aplicación: un endpoint de health público, una solicitud de prueba autenticada o un smoke test proporcionado por el repositorio que no modifique datos de clientes.

El resultado final debe indicar ambas capas. “El deployment de la plataforma se completó correctamente” y “el smoke test de la aplicación pasó” son afirmaciones diferentes. Cuando solo esté disponible la primera, Codex debe decirlo en lugar de convertir la incertidumbre en un check verde.

Confirma la superficie de comandos instalada antes de automatizar

Una tarea reutilizable de Codex debería comenzar comprobando dockup skill status --json y abriendo la referencia actual de la CLI cuando dependa de una opción menos conocida. Así se evita que una sesión siga un ejemplo escrito para otra release.

Esta comprobación resulta especialmente útil en runners efímeros, donde una instalación global nueva de npm puede diferir de la de un portátil de desarrollo. Codex puede informar del estado de la skill antes de realizar la primera escritura en producción, haciendo reproducible el registro del deployment.

Entrega final

Conserva las evidencias.

Mantén visible el target

Devuelve el target exacto del servicio en el informe final.

Conserva la decisión sobre el origen

Registra si Dockup utilizó el Dockerfile del repositorio o Nixpacks. Este dato ayuda a la siguiente sesión de Codex a elegir el build log correcto y evita confundir un cambio en la estructura del código fuente con un incidente de la plataforma.

Registra también si el deploy automático al hacer push está activado. De lo contrario, una release manual del agente y una release activada por push podrían solaparse y crear dos eventos de producción a partir de la misma investigación.

Lleva el flujo de trabajo a producción

Ejecuta el primer deployment de Codex contra un servicio desechable o de bajo riesgo y, después, promueve el mismo contrato de comandos verificado a producción.

npm install -g dockup-cli
dockup skill install

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

Preguntas frecuentes

¿Puede Codex desplegar un repositorio Git nuevo con un solo comando?

Sí. dockup create puede crear el servicio, hacer el deploy, esperar el resultado terminal y enlazar el directorio actual cuando se utiliza con --deploy, --wait y --link.

¿Cómo debe autenticarse Codex en Dockup?

Utiliza DOCKUP_TOKEN en el entorno del proceso y verifícalo con dockup whoami --json. Así se evita el login interactivo mediante navegador en sandboxes y CI.

¿Qué demuestra que un deployment de Codex se ha completado correctamente?

El comando deploy debe terminar con el código 0 después de ejecutarse con --wait, y su JSON debe informar de un estado terminal correcto. Después, ejecuta comprobaciones de status, uptime y smoke tests de la aplicación.

¿Puede Codex leer los secrets de producción de Dockup?

No. Los valores secretos aparecen ocultos en el output. Codex puede establecer o reemplazar un secret, pero no recibe el valor almacenado al listar la configuración.

¿Qué debe hacer Codex con needs_confirm?

Debe detenerse y solicitar aprobación humana explícita. El error indica que se intentó ejecutar un comando destructivo sin la confirmación --yes requerida.