Déploiement de Claude Code : guide de production

Le déploiement de Claude Code devient fiable uniquement lorsque l’agent sait faire la différence entre « demande acceptée » et « production opérationnelle ». Dockup fournit cette couche de déploiement via une CLI conçue pour les appels automatisés : JSON structuré, vrais codes de sortie du processus et mode --wait qui reste attaché jusqu’à ce qu’un déploiement atteigne un état final.

Ce guide accompagne un dépôt depuis le travail local jusqu’à une release de production vérifiée. Il définit également les permissions que Claude Code doit recevoir, les éléments de preuve qu’il doit renvoyer et le moment où une personne doit approuver une action destructive.

De quoi Claude Code a-t-il besoin avant un déploiement en production ?

Un agent de développement ne doit pas commencer par deviner le nom d’un service ou parcourir un dashboard. Fournissez-lui un contrat opérationnel précis : identifier la cible exacte, effectuer une seule modification prévue, attendre le résultat et fournir des éléments de preuve lisibles par machine.

Les prérequis de base sont simples :

Requirement	Why it matters	Verification
Node.js 18 or newer	Required by the Dockup CLI package	node --version
Dockup account	Owns workspaces, services, and databases	Sign in at app.dockup.ai
Git repository	Source for the service build	Confirm the remote URL and branch
API token	Non-interactive authentication	dockup whoami --json
Health endpoint or listening port	Gates the blue-green cutover	dockup health ... --json

Définissez la limite de production avant que l’agent n’agisse. Claude Code peut créer un service, définir une configuration non sensible, déclencher un déploiement, consulter les logs et proposer un rollback. Il ne doit pas supprimer un service, supprimer une base de données ou purger la configuration sans approbation explicite d’une personne.

Dockup renforce cette limite. Les commandes destructives refusent de s’exécuter sans --yes et renvoient une erreur structurée needs_confirm au lieu d’interpréter l’absence de confirmation comme une invitation à improviser. Pour une politique plus complète, consultez les garde-fous de production pour les agents IA.

Comment installer la skill Claude Code et s’authentifier en toute sécurité ?

Installez la CLI, installez la skill fournie avec celle-ci et vérifiez que la skill correspond au binaire installé :

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

L’installateur écrit la skill canonique dans ~/.agents/skills/dockup/ et la lie au répertoire des skills de Claude Code. Comme la skill est fournie dans le même package npm que la CLI, dockup update met à jour les deux. Claude Code n’a pas à se fier à une copie de la référence des commandes qui pourrait décrire des options non prises en charge par son binaire local.

Utilisez un token d’environnement pour les sessions autonomes :

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

Une réponse réussie identifie le compte et indique tokenSource à env. Ne collez pas le token dans un prompt, ne le commitez pas dans le dépôt et ne l’affichez pas dans un log CI. Les valeurs secrètes stockées dans Dockup sont masquées lorsque la configuration est relue.

La référence complète de la Dockup CLI fait autorité pour les commandes disponibles. Avec 135 commandes, Claude Code doit consulter la référence à jour et la skill fournie avec le package plutôt que de se fier à des options mémorisées.

Comme la skill est incluse dans le package de la CLI, dockup update actualise l’exécutable et ses instructions simultanément. Cet alignement des versions est plus sûr que de copier une liste de commandes dans un prompt conservé à long terme.

Comment la Dockup CLI crée-t-elle un service depuis Git ?

Commencez par demander à l’agent d’identifier le workspace et évitez de construire des slugs à partir des noms affichés. Les cibles existantes sont renvoyées par :

dockup services --json

Pour un dépôt qui n’a encore jamais été déployé, une seule transaction peut créer le service, le déployer, attendre la fin de l’opération et lier le répertoire courant :

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

Lorsque le dépôt contient un Dockerfile, Dockup l’utilise. En son absence, Dockup utilise Nixpacks pour détecter automatiquement le processus de build. Le choix est expliqué dans Nixpacks ou Dockerfile, notamment pour déterminer quand des instructions de build explicites justifient leur coût de maintenance.

Avant de relancer la création après une session interrompue, exécutez à nouveau dockup services --json et inspectez la cible exacte. Si le service existe déjà, reprenez à partir de son état au lieu d’envoyer une nouvelle demande de création.

Une fois le lien établi, les commandes exécutées dans ce dépôt peuvent résoudre la cible depuis .dockup, mais les runbooks de production doivent tout de même enregistrer la valeur complète project/service. La découverte constitue la limite sûre entre une action précédente incertaine et une nouvelle modification de la production.

Comment préparer les variables d’environnement, les bases de données et les health checks ?

Séparez la configuration ordinaire des secrets. Claude Code peut définir une valeur publique d’exécution et un secret masqué sans afficher ensuite les valeurs secrètes stockées :

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

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

Les modifications d’environnement s’appliquent au prochain déploiement. C’est intentionnel : un conteneur en cours d’exécution conserve son environnement de processus actuel jusqu’à son remplacement. Le fonctionnement complet est présenté dans les variables d’environnement et les secrets.

Si l’application a besoin d’une base de données PostgreSQL managée, créez-la dans le workspace sélectionné et consultez ses informations avec les commandes documentées pour les bases de données :

dockup db create --name main-db --type postgresql --json
dockup db list --json

La mise en réseau privée peut ensuite fournir aux services et aux bases de données des hostnames stables au format <slug>.internal au sein d’un même projet. Ne demandez pas à l’agent d’inventer une URL de connexion à la base de données ; utilisez les informations de connexion renvoyées par Dockup et stockez-les comme secret.

Configurez une condition de readiness avant la première release de production importante :

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

Dockup effectue un déploiement blue-green sans interruption et ne redirige le trafic vers la nouvelle version qu’une fois le health check réussi. L’architecture est présentée dans les déploiements sans interruption.

Comment Claude Code déploie-t-il et prouve-t-il que l’opération a réussi ?

Utilisez --wait ; ne laissez pas l’agent interpréter « déploiement mis en file d’attente » comme « application en cours d’exécution » :

dockup deploy production/my-api --wait --json

Le délai d’attente par défaut est de 900 secondes. En cas de réussite, la commande se termine avec le code 0 et renvoie l’état final, la durée, l’identifiant du déploiement et l’URL. Si le build échoue, elle se termine avec un code différent de zéro et code:"deploy_failed". Si l’opération est toujours en cours à l’expiration du délai, elle se termine avec un code différent de zéro et code:"deploy_timeout".

Une instruction utile à donner à Claude Code est : « Traite le code de sortie du processus comme le résultat principal, puis résume les champs JSON. » Cela évite les formulations trop optimistes lorsque la plateforme a déjà renvoyé un échec.

Après une réussite, recueillez trois signaux indépendants :

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

status confirme l’état du service et celui du dernier déploiement. uptime renvoie des statistiques de monitoring minute par minute, notamment le temps de réponse moyen et le p95. security affiche les résultats du dernier scan des CVE de l’image et de la configuration. Ces vérifications complètent les pratiques de sécurité au niveau de l’application ; elles ne remplacent pas les tests applicatifs.

Que doit faire Claude Code lorsque la production échoue ?

Faites la distinction entre un échec de build et un échec à l’exécution. Un build en échec nécessite le dernier build log :

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

Un conteneur qui a été construit mais qui plante après son démarrage nécessite les logs d’exécution :

dockup logs production/my-api --json

Pour suivre un build tout en conservant des lots lisibles par machine, utilisez le mode de suivi NDJSON :

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

La commande s’arrête lorsque le déploiement atteint un état final et se termine avec un code différent de zéro en cas d’échec. Claude Code peut diffuser la progression sans inventer une boucle de polling.

Si la release actuelle n’est pas saine et qu’un déploiement précédent connu doit être relancé, consultez l’historique et utilisez son identifiant exact :

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

L’agent doit indiquer quel identifiant de déploiement il a sélectionné et pourquoi. Un rollback est une décision opérationnelle, pas un substitut à la compréhension de l’échec. Conservez le build log, le runtime log, le code de sortie et l’enregistrement d’audit afin de pouvoir reconstituer l’incident.

Un rapport de déploiement Claude Code terminé doit inclure la cible, le commit ou la branche, l’identifiant du déploiement, l’état final, l’URL, le temps écoulé, le résultat du health check et les éventuels risques à traiter. Ces éléments de preuve transforment une action autonome en modification de production vérifiable.

Définir un contrat de finalisation pour la production

Avant de commencer, incluez le contrat de finalisation attendu dans la tâche. Une demande utile consiste à déployer le dépôt lié vers production/my-api, attendre un résultat final, ne rien supprimer, purger ni transférer, et, en cas d’échec, renvoyer le code d’erreur ainsi que les 60 dernières lignes pertinentes du build log ; en cas de réussite, renvoyer l’état, l’URL, l’identifiant du déploiement, la durée et les éléments de preuve du health check.

Cette formulation donne à Claude Code un objectif délimité et un schéma de compte rendu. Elle empêche également l’agent de modifier « utilement » une infrastructure sans rapport lorsque la release échoue. L’agent peut proposer une correction distincte, mais l’action de production reste attribuable à une seule demande.

Pour les releases répétées, conservez un enregistrement de release succinct dans le dépôt ou le système de gestion des changements. Notez la cible, la branche source, le chemin de health check attendu, le délai d’attente habituel et l’action de récupération approuvée. Un déploiement de Claude Code est plus sûr lorsque la session suivante n’a pas à reconstituer ces informations à partir de l’historique des conversations.

Vérifier la limite du compte avant la première écriture

Les workspaces constituent des limites de propriété et de facturation. Demandez à Claude Code d’afficher whoami, de lister les services et d’indiquer le workspace sélectionné avant toute modification. Le forfait Pro coûte 20 $ par mois et inclut 20 $ de crédit d’utilisation ; il s’agit du forfait payant recommandé. Tous les forfaits payants autorisent un nombre illimité de workspaces, de bases de données et de déploiements, tandis que l’utilisation du CPU, de la RAM et du disque est mesurée à la minute et déduite du solde du forfait.

Ce modèle tarifaire ne change pas la règle de sécurité : un agent doit inspecter l’utilisation et le périmètre de la cible avant d’augmenter les ressources ou d’en créer de nouvelles. Le rapport de production doit distinguer le forfait souscrit de la consommation réellement mesurée.

Mettre le workflow en production

Installez la skill dans le même environnement que celui où Claude Code s’exécutera, vérifiez l’authentification et commencez par un service peu risqué dont le health endpoint est déjà connu.

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

Claude Code peut-il déployer directement en production avec Dockup ?

Oui. Installez la skill Dockup, fournissez un DOCKUP_TOKEN limité, résolvez la cible exacte au format projet/service et exécutez la commande de déploiement avec --wait et --json.

Pourquoi Claude Code doit-il utiliser --wait ?

Sans --wait, une réponse réussie signifie uniquement que le déploiement a été mis en file d’attente. Avec --wait, Dockup ne se termine avec le code 0 qu’une fois l’opération réussie et renvoie sinon les erreurs structurées deploy_failed ou deploy_timeout.

Claude Code voit-il les valeurs secrètes stockées ?

Dockup masque les valeurs secrètes dans la sortie. L’agent peut définir ou remplacer un secret, mais la lecture de la configuration d’environnement ne renvoie pas sa valeur stockée.

Que se passe-t-il lorsqu’un dépôt ne contient pas de Dockerfile ?

Dockup utilise Nixpacks pour détecter et construire automatiquement l’application. Le Dockerfile du dépôt est prioritaire lorsqu’il est présent.

Comment Claude Code peut-il récupérer une mauvaise release ?

Il doit consulter les logs de build et d’exécution, lister l’historique des déploiements et relancer un déploiement précédent connu avec dockup rollback en utilisant l’identifiant exact du déploiement.