CI/CD d’agent IA avec DOCKUP_TOKEN

Le CI/CD d’agent IA ne fonctionne correctement que lorsque l’authentification et le déploiement s’effectuent sans intervention humaine au terminal. La connexion via navigateur, la saisie de codes à usage unique copiés manuellement et les simples messages d’état en langage naturel sont incompatibles avec un runner sans surveillance. Dockup prend en charge ce fonctionnement non interactif grâce à DOCKUP_TOKEN, au JSON structuré et à des commandes de déploiement qui renvoient un véritable code de sortie d’échec.

Ce guide définit un contrat de pipeline utilisable aussi bien par Claude Code, Codex, un script shell ou une tâche CI classique. Les mêmes règles s’appliquent : injecter le token au moment de l’exécution, vérifier l’identité, découvrir ou spécifier la cible exacte, attendre un résultat terminal et conserver les diagnostics en cas d’échec.

Pourquoi le CI/CD d’agent IA nécessite-t-il une authentification non interactive ?

La commande interactive dockup login ouvre une page d’authentification et attend un token. Cette approche convient à un poste de développement, mais un runner conteneurisé peut ne disposer ni d’un navigateur, ni d’un répertoire personnel persistant, ni d’une personne pouvant saisir quoi que ce soit.

DOCKUP_TOKEN résout cette contrainte :

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

La variable d’environnement est prioritaire sur ~/.dockup/config.json. whoami indique tokenSource, ce qui permet au pipeline de vérifier qu’il utilise bien l’identifiant injecté prévu, et non un ancien fichier de configuration laissé sur un runner auto-hébergé.

N’exécutez pas dockup login -t "$DOCKUP_TOKEN" en CI, sauf raison précise nécessitant la persistance d’un fichier de configuration. Fournir directement la variable d’environnement limite la portée de l’identifiant au processus et évite de l’écrire dans le répertoire personnel du runner.

Le pipeline ne doit jamais afficher le token. Désactivez le traçage du shell autour des commandes contenant des secrets, évitez d’afficher l’environnement complet et utilisez le mécanisme de masquage des secrets fourni par la plateforme CI.

Comment stocker et limiter la portée de DOCKUP_TOKEN ?

Stockez le token dans un gestionnaire chiffré de secrets au niveau du dépôt, de l’environnement ou de l’organisation. Préférez un secret au niveau de l’environnement pour la production, car il peut être associé à des restrictions de branche et à des validations manuelles proposées par la plateforme CI.

Une politique sécurisée pour les tokens doit répondre à cinq questions :

Question	Réponse recommandée
Où le token est-il stocké ?	Gestionnaire de secrets chiffrés de la CI
Quand est-il exposé ?	Uniquement dans la tâche de déploiement
Quelles branches peuvent l’utiliser ?	Branches de production protégées
Qui peut modifier le workflow ?	Mainteneurs ayant fait l’objet d’une review
Comment son utilisation est-elle contrôlée ?	Journal d’audit Dockup et historique des tâches CI

Dockup prend également en charge les clés API avec permissions. Listez les noms de permissions disponibles avant de créer une clé à portée limitée :

dockup keys permissions --json

Choisissez uniquement les noms de permissions exacts renvoyés par la plateforme, puis créez la clé via le workflow de clés API avec permissions. Récupérez la clé générée de manière sécurisée lors de sa création, stockez-la immédiatement et ne l’incluez ni dans une issue, ni dans une pull request, ni dans le transcript d’un agent ; une tâche de déploiement ne doit pas hériter de droits d’administration étendus simplement parce qu’un token de développeur les possède déjà.

L’article Garde-fous de production pour les agents IA présente une échelle de permissions plus complète.

Comment créer un pipeline de déploiement qui attend la réalité de l’état ?

Installez la CLI dans la tâche, vérifiez l’identité, puis déployez avec --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

L’élément important n’est pas le fournisseur CI, mais le contrat de commande. dockup deploy ... --wait --json ne se termine avec le code 0 que lorsque le déploiement atteint l’état réussi. Le délai d’expiration par défaut est de 900 secondes. Un build échoué renvoie une sortie différente de zéro avec deploy_failed ; une opération qui n’atteint pas un état terminal avant l’expiration renvoie deploy_timeout.

Comme le processus se termine avec une sortie différente de zéro, le runner marque l’étape et la tâche comme échouées. Aucun parsing des logs n’est nécessaire.

Pour un dépôt lié qui doit pousser sa branche actuelle puis la déployer, dockup push --json attend par défaut. Dans une tâche CI ayant déjà reçu un événement Git push, une commande explicite dockup deploy <target> est souvent plus claire, car elle évite d’effectuer un push depuis le runner.

Comment un pipeline doit-il capturer les logs et les codes d’erreur ?

Conservez le résultat JSON du déploiement comme artifact ou sortie de tâche, mais veillez à ce qu’une redirection ne masque pas le code de sortie. Un pattern shell permet de capturer les deux :

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

Le pipeline se termine avec le code de sortie d’origine du déploiement. Les logs de build sont collectés uniquement après un échec. Les logs d’exécution doivent être collectés lorsque l’image a été construite, mais que l’application plante ensuite :

dockup logs production/api --json

Pour suivre en direct la progression du build, le mode follow émet du NDJSON :

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

Le flux se termine lorsque le déploiement se termine, et l’échec reste signalé par un résultat de processus différent de zéro. La séquence détaillée de diagnostic est présentée dans le débogage des logs de build et d’exécution.

Un pipeline doit se baser sur les codes, et non sur des fragments de messages :

Code	Réponse du pipeline
not_logged_in	Échouer immédiatement ; l’injection du secret est défaillante
no_target	Échouer ; la configuration de la cible est invalide
deploy_trigger_failed	Échouer avant l’attente ; examiner l’erreur renvoyée
deploy_failed	Importer les logs de build et échouer
deploy_timeout	Marquer l’état comme incertain ; vérifier le statut avant de réessayer
needs_confirm	Arrêter ; une étape destructive n’a pas reçu l’approbation nécessaire

Comment un agent peut-il participer sans affaiblir la sécurité de la CI ?

Un agent peut préparer le code, mettre à jour un workflow soumis à review, interpréter du JSON et résumer un build échoué. Il n’a pas besoin d’un accès illimité au token de production pendant chaque session de développement.

Séparez les rôles :

1. Agent de développement : modifie le code et exécute les tests en local.
2. Processus de review : valide les modifications de la configuration de déploiement.
3. Runner CI : reçoit DOCKUP_TOKEN uniquement après le déclencheur approuvé.
4. Dockup : exécute le déploiement et enregistre les événements d’audit.
5. Agent ou opérateur : interprète le résultat et propose une procédure de récupération.

Cette organisation empêche une prompt injection dans une tâche sans rapport d’obtenir les identifiants de production. L’agent peut tout de même comprendre le pipeline, car les commandes et le JSON attendu sont versionnés dans le dépôt, tandis que la valeur du secret reste à l’extérieur.

Pour les déploiements exécutés directement par un agent, injectez le token dans le processus Claude Code ou Codex concerné et installez la skill incluse :

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

La skill indique aux deux agents d’utiliser l’authentification non interactive, le JSON, la découverte exacte de la cible, l’attente d’un état terminal et les étapes de confirmation.

Qu’est-ce qui rend le CI/CD d’agent IA reproductible et auditable ?

La reproductibilité commence par une cible explicite. Stockez production/api comme variable de pipeline protégée ou comme valeur littérale soumise à review, plutôt que comme un nom que l’agent déduirait au moment de l’exécution. Validez le compte avant la première écriture.

L’idempotence nécessite un traitement différent selon l’opération :

• La lecture de l’identité, du statut, des logs et de l’historique peut être répétée sans risque.
• La création d’un service doit commencer par une découverte de la cible afin que les nouvelles tentatives ne créent pas de doublon.
• Un nouveau déploiement crée un autre événement de production et doit être enregistré.
• Les modifications d’environnement sont des mutations et nécessitent un nouveau déploiement.
• La destruction et le pruning ne doivent pas être des opérations relancées automatiquement.

Après le déploiement, collectez les éléments de preuve fournis par la plateforme :

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

La disponibilité est mesurée chaque minute et inclut le temps de réponse moyen ainsi que le p95. La sortie d’audit relie la mutation effectuée par la CI à la review ultérieure. La consommation de CPU, de RAM et de disque est également mesurée chaque minute par rapport au solde du compte ; le forfait Pro recommandé coûte 20 $ par mois avec un crédit d’utilisation de 20 $.

Un enregistrement complet du pipeline comprend le commit Git, la cible Dockup, l’ID du déploiement, les horodatages de début et de fin, le code de sortie, le statut terminal et les liens vers les artifacts de build. Cela rend une release de CI/CD d’agent IA reproductible, même lorsque la session originale de l’agent n’existe plus.

La référence de la CLI Dockup doit être considérée comme la source de référence des commandes. Pour créer un dépôt avant d’activer la CI, suivez le guide Du dépôt Git à la production.

Contrôler la concurrence et la promotion entre environnements

Deux pipelines réussis peuvent tout de même créer une release dangereuse s’ils s’exécutent simultanément sur la même cible. Utilisez les contrôles de concurrence de la plateforme CI afin qu’une nouvelle tâche de production attende une tâche plus ancienne ou la remplace délibérément. Dockup signalera fidèlement chaque déploiement, mais le workflow du dépôt doit déterminer l’ordre des commits qui se chevauchent.

Faites progresser le même commit soumis à review entre les environnements, plutôt que de reconstruire un état local non suivi. Une tâche de staging peut déployer staging/api, exécuter les vérifications de l’application, puis autoriser une tâche de production protégée à déployer production/api. Gardez les tokens et les cibles distincts afin qu’un agent de staging ne puisse pas franchir accidentellement cette limite.

Définir une politique de nouvelle tentative en cas d’expiration

deploy_timeout ne signifie ni échec ni succès. Cela signifie que l’opération était toujours en cours lorsque l’attente de 900 secondes s’est terminée. Avant de réessayer, inspectez :

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

Si le déploiement d’origine atteint ensuite l’état réussi, une nouvelle tentative aveugle créerait une autre release. S’il a échoué, récupérez le log de build. S’il reste dans un état non terminal et que le build est légitimement long, relancez l’observation avec un délai d’expiration plus élevé et documenté, au lieu de créer un deuxième déploiement.

Cette distinction empêche le CI/CD d’agent IA de transformer une incertitude réseau ou temporelle en modifications de production dupliquées.

Enregistrer l’identité du déploiement

Incluez l’identité du compte Dockup, la cible, le SHA du commit, l’ID du déploiement et le statut terminal dans le résumé CI. Cet enregistrement simple permet à un opérateur ultérieur de relier l’exécution du pipeline aux événements d’audit Dockup sans exposer le token.

Mettre le workflow en production

Installez la CLI dans le runner, vérifiez l’identité injectée et utilisez le statut de sortie terminal — et non une ligne de log semblant indiquer un succès — comme gate du pipeline.

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

Qu’est-ce que DOCKUP_TOKEN ?

DOCKUP_TOKEN est le mode d’authentification fondé sur une variable d’environnement pour les sessions de la CLI Dockup qui ne peuvent pas effectuer une connexion interactive via navigateur, notamment les runners CI, les conteneurs et les agents IA.

DOCKUP_TOKEN remplace-t-il un fichier de configuration Dockup local ?

Oui. Le token d’environnement est prioritaire, et dockup whoami --json indique la source du token actif.

Comment une tâche CI sait-elle qu’un déploiement Dockup a échoué ?

Exécutez dockup deploy avec --wait et --json. La commande se termine avec un code différent de zéro et un code d’échec structuré lorsque le déploiement échoue ou expire.

Un workflow CI doit-il afficher le token de déploiement pour faciliter le débogage ?

Non. Conservez-le dans le gestionnaire de secrets de la CI, évitez le traçage du shell et l’affichage de l’environnement, et exposez-le uniquement à l’étape de déploiement.

Claude Code ou Codex peuvent-ils utiliser le même mode d’authentification CI ?

Oui. Tous deux peuvent utiliser DOCKUP_TOKEN et la skill Dockup incluse, qui leur apprend les mêmes règles de JSON, de découverte de cible, d’attente et de confirmation.