Déploiement de Codex : workflow Dockup de bout en bout

Un déploiement de Codex doit se conclure par des preuves, pas par une supposition. La difficulté pratique n’est pas de demander à Codex d’exécuter une commande de déploiement, mais de fournir à l’agent une interface qui identifie précisément la cible, attend un état terminal, renvoie les véritables codes de sortie et expose les détails des erreurs sans navigateur.

Dockup constitue la couche de déploiement de ce workflow. Sa CLI fournit à Codex du JSON structuré pour chaque commande prise en charge, et sa skill intégrée apprend à l’agent à s’authentifier, découvrir les services, déployer, diagnostiquer et s’arrêter avant toute opération destructive.

Comment installer la skill CLI de Codex ?

Installez la CLI globalement, puis exécutez l’installateur de skill en une seule commande. Il écrit la skill canonique et la lie à Claude Code et Codex :

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

La skill canonique se trouve dans ~/.agents/skills/dockup/ et est liée symboliquement à ~/.codex/skills/. Elle est incluse dans dockup-cli : une mise à jour standard modifie donc l’exécutable et ses instructions simultanément :

dockup update

Ce couplage des versions est important lorsque la surface de commandes est étendue. Un agent ne doit jamais exécuter un flag mémorisé simplement parce qu’il apparaissait dans un ancien prompt. Codex doit utiliser la skill fournie avec le package et la référence actuelle de la Dockup CLI comme source d’autorité pour les commandes.

Pour comprendre les choix de conception liés aux skills, consultez skills d’agents et MCP.

Comment Codex s’authentifie-t-il sans terminal interactif ?

Un sandbox ou un job CI peut ne pas être en mesure d’effectuer une connexion via navigateur. Définissez un token dans l’environnement du processus :

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

DOCKUP_TOKEN est prioritaire sur le fichier de configuration local. La réponse de whoami indique si l’identifiant actif provient de l’environnement ou de la configuration, ce qui aide Codex à diagnostiquer le cas courant où un token local obsolète et un token CI coexistent.

Traitez le token comme un secret d’infrastructure. Ne le placez pas dans AGENTS.md, SKILL.md, le contrôle de version, des exemples de commandes commités dans le repository ni dans la transcription finale de l’agent. En CI, utilisez le gestionnaire de secrets chiffrés de la plateforme et n’exposez la valeur qu’à l’étape de déploiement. Le workflow complet sans interaction est décrit dans CI/CD avec DOCKUP_TOKEN.

Avant d’accorder à Codex un accès en écriture, définissez son périmètre d’autorisations. Une première portée raisonnable comprend la découverte des services, le déploiement, la lecture des logs et les vérifications de statut. La suppression de bases de données, la destruction de services, les modifications d’équipe et le nettoyage de la configuration doivent rester soumis à approbation.

Comment Codex trouve-t-il ou crée-t-il le bon service ?

Faites de la découverte la première opération. Ne demandez pas à Codex de transformer « Payments API » en slug deviné :

dockup services --json

Chaque résultat inclut une target exacte au format project/service. Codex doit recopier cette valeur dans les commandes suivantes et la restituer dans son récapitulatif.

Lorsqu’aucun service n’existe, créez-en un à partir de Git :

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

La commande crée le service, le déploie, bloque jusqu’à la résolution du déploiement et écrit un lien .dockup dans le répertoire de travail. Un Dockerfile est utilisé lorsqu’il est présent ; sinon, Nixpacks effectue une détection automatique du build.

Lorsque Codex perd l’état de la session ou qu’un workflow est relancé après une interruption réseau, il doit redécouvrir les services et inspecter la cible exacte avant toute modification. Si la cible existe déjà, il doit reprendre à partir de son statut et de son historique de déploiement au lieu d’envoyer une nouvelle requête de création.

La séquence complète, du repository à la production, est disponible dans Du repository Git à la production.

Comment Codex doit-il préparer la configuration avant le déploiement ?

Demandez à Codex d’inspecter les métadonnées actuelles du service avant de les modifier :

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

La réponse concernant l’environnement inclut les clés et les marqueurs isSecret, tandis que les valeurs secrètes restent masquées. Codex peut ajouter séparément les variables ordinaires et les secrets :

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

Ne placez jamais un secret de production dans dockup.yaml ; le manifest convient à une configuration ordinaire pouvant être relue, pas aux identifiants. Les variables secrètes existantes ne sont ni écrasées ni supprimées par le workflow config-as-code.

Configurez le port d’écoute du service et le readiness check lorsqu’ils sont connus :

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

Un readiness gate rend la vérification de production pertinente. La plateforme effectue un déploiement blue-green et ne route le trafic qu’une fois que la nouvelle version satisfait cette condition.

Comment la vérification de production confirme-t-elle l’état terminal ?

Pour un service existant, utilisez une seule commande :

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

Le timeout explicite correspond à la valeur par défaut de 900 secondes et rend l’intention du workflow visible. Le code de sortie 0 signifie que le déploiement a réussi. Un résultat non nul avec deploy_failed signifie que le build ou le déploiement a échoué. deploy_timeout signifie que l’opération n’était pas encore dans un état terminal à la fin de la période d’attente.

La logique de branchement correcte pour Codex repose sur le statut du processus :

Résultat	Action de Codex
Exit 0, status:"success"	Poursuivre avec les vérifications de health, d’uptime et de sécurité
deploy_failed	Lire les build logs et identifier la première erreur exploitable
deploy_timeout	Signaler l’incertitude ; inspecter le statut ou réessayer avec un timeout justifié
not_logged_in	S’arrêter et demander un token valide
needs_confirm	S’arrêter et demander l’approbation d’un humain

Après un déploiement Codex réussi, recueillez des preuves observables :

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

Les vérifications d’uptime s’exécutent chaque minute et incluent des statistiques de temps de réponse telles que le p95. Les résultats de sécurité incluent les CVE de l’image et des vérifications de configuration. Ces signaux ne prouvent pas que l’application fonctionne correctement sur le plan métier ; Codex doit donc également exécuter les smoke tests du repository lorsqu’ils sont disponibles.

Comment Codex doit-il diagnostiquer et récupérer après une release échouée ?

Les erreurs de build et les erreurs d’exécution nécessitent des logs différents. Utilisez la dernière sortie de build lorsque le déploiement n’a jamais atteint l’étape d’un conteneur exécutable :

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

Utilisez les runtime logs lorsque l’image a été construite mais que l’application plante, écoute sur le mauvais port ou échoue après son démarrage :

dockup logs production/payments-api --json

Le mode follow est utile pendant un build long :

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

En mode JSON, la sortie du mode follow est au format NDJSON, ce qui permet à Codex de traiter chaque lot dès son arrivée. Le flux se termine lorsqu’un état terminal du déploiement est atteint et conserve le véritable code de sortie de l’erreur.

La récupération commence par l’historique, pas par une cible de rollback devinée :

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

Codex doit identifier un déploiement connu comme réussi, indiquer l’ID sélectionné et conserver les preuves de l’échec avant de le relancer. Il ne doit jamais choisir « le deuxième élément » sans vérifier le statut et les horodatages.

Un rapport final utile comporte sept champs : cible, branche ou commit, ID du déploiement, code de sortie, statut terminal, URL de production et actions de suivi. Ce format rend chaque déploiement Codex vérifiable par une personne ou une étape d’automatisation ultérieure.

Un script de vérification compact

Ce pattern shell conserve le déploiement et le diagnostic dans un même flux de contrôle transparent :

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

Le script ne recherche pas une phrase de succès avec grep. Il se fie au code de sortie de la CLI, conserve le JSON du déploiement et fait échouer le job appelant lorsque la production n’a pas atteint l’état de réussite.

Rendez les retries observables plutôt qu’invisibles

Les sessions d’agents peuvent être interrompues après le démarrage d’une opération, mais avant que le résultat n’atteigne la transcription. La prochaine exécution de Codex ne doit pas répéter aveuglément chaque modification. Elle doit redécouvrir le service, inspecter le dernier déploiement et déterminer si l’opération précédente a atteint un état terminal.

Un runbook de déploiement Codex doit classer les commandes comme répétables sans risque, répétables uniquement après inspection ou soumises à approbation. Les lectures peuvent être répétées sans risque. La création d’un service nécessite d’abord une découverte. Un nouveau déploiement constitue un nouvel événement de production et doit être enregistré comme tel. Le pruning et les autres opérations destructives restent des décisions humaines.

Séparez la vérification de la plateforme de celle de l’application

Dockup peut prouver qu’un build est terminé, que le conteneur est prêt et que des probes à la minute observent le service public. Codex doit toutefois exécuter des vérifications propres à l’application : un endpoint de health public, une requête de test authentifiée ou un smoke test fourni par le repository qui ne modifie pas les données client.

Le résultat final doit présenter les deux niveaux. « Le déploiement de la plateforme a réussi » et « le smoke test de l’application a réussi » sont deux affirmations différentes. Lorsque seul le premier élément est disponible, Codex doit le préciser au lieu de transformer l’incertitude en coche verte.

Confirmez la surface de commandes installée avant l’automatisation

Une tâche Codex réutilisable doit commencer par vérifier dockup skill status --json et ouvrir la référence actuelle de la CLI lorsqu’elle dépend d’une option moins familière. Cela évite qu’une session ne suive un exemple écrit pour une autre release.

Cette vérification est particulièrement utile dans les runners éphémères, où une nouvelle installation globale de npm peut différer de celle d’un laptop de développeur. Codex peut signaler l’état de la skill avant d’effectuer la première écriture en production, ce qui rend le déploiement reproductible.

Handoff final

Conservez les preuves.

Gardez la cible visible

Renvoyez la cible exacte du service dans le rapport final.

Préservez la décision concernant la source

Indiquez si Dockup a utilisé le Dockerfile du repository ou Nixpacks. Cette information aide la session Codex suivante à choisir les bons build logs et évite qu’un changement dans la structure du code source ne soit pris pour un incident de plateforme.

Indiquez également si le déploiement automatique à chaque push est activé. Une release manuelle par l’agent et une release déclenchée par un push peuvent sinon se chevaucher et créer deux événements de production à partir de la même investigation.

Mettez le workflow en production

Effectuez le premier déploiement Codex sur un service jetable ou peu risqué, puis promouvez le même contrat de commandes vérifié en production.

npm install -g dockup-cli
dockup skill install

La première commande installe la CLI. La seconde installe la skill Dockup correspondante pour Claude Code et Codex. Commencez gratuitement sur app.dockup.ai.

FAQ

Codex peut-il déployer un nouveau repository Git avec une seule commande ?

Oui. dockup create peut créer le service, le déployer, attendre le résultat terminal et lier le répertoire courant lorsqu’elle est utilisée avec --deploy, --wait et --link.

Comment Codex doit-il s’authentifier auprès de Dockup ?

Utilisez DOCKUP_TOKEN dans l’environnement du processus et vérifiez-le avec dockup whoami --json. Cela évite la connexion interactive via navigateur dans les sandbox et les environnements CI.

Qu’est-ce qui prouve qu’un déploiement Codex a réussi ?

La commande deploy doit se terminer avec le code 0 après une exécution avec --wait, et son JSON doit indiquer un statut terminal réussi. Enchaînez avec des vérifications de status, d’uptime et des smoke tests de l’application.

Codex peut-il lire les secrets de production depuis Dockup ?

Non. Les valeurs secrètes sont masquées dans la sortie. Codex peut définir ou remplacer un secret, mais ne reçoit pas la valeur stockée lors de l’affichage de la configuration.

Que doit faire Codex avec needs_confirm ?

Il doit s’arrêter et demander l’approbation explicite d’un humain. Cette erreur indique qu’une commande destructive a été tentée sans la confirmation --yes requise.