Guide pratique Codex Cloud : confier une tâche GitHub à un agent cloud et valider le résultat

Un GitHub issue dit : “Le test webhook échoue en CI, mais je ne peux pas lancer l’environnement complet en local maintenant.” Vous voulez laisser Codex Cloud corriger le dépôt côté cloud, puis ne récupérer que le diff, le journal de tests et le PR à valider.

Le sujet n’est pas que le cloud serait plus automatique. L’intérêt est qu’une Cloud task tourne dans un environnement de dépôt propre, reproductible, séparé de votre machine. Elle ne lit ni vos fichiers locaux non commités, ni votre session navigateur, ni votre .env local. Cette limite est aussi une protection utile.

Voici le flux que j’utilise : décider si la tâche doit aller dans Cloud, configurer l’environnement, écrire le prompt, inspecter le résultat, puis choisir entre ouvrir un PR, rapatrier le diff en local ou lancer @codex review comme deuxième contrôle.

Décider d’abord : cette demande doit-elle aller dans Cloud ou rester en local ?

Les limites entre Local, Worktree, Cloud et SSH host

Les points d’entrée Codex ne résolvent pas le même problème. Ce n’est pas une simple échelle de puissance.

Cloud n’est pas un “Worktree plus puissant”. Worktree tourne encore sur votre machine ; il sépare seulement le répertoire Git. Cloud est un configured cloud environment qui checkout le dépôt GitHub et exécute la tâche dans un conteneur distant.

Une bonne tâche Cloud a généralement quatre propriétés : un objectif clair, un état de dépôt reproductible, un environnement scriptable et un Done when vérifiable par une commande ou un diff. Corriger un CI failure, compléter une documentation, traiter un retour de PR review ou ajouter des tests à un module précis entrent bien dans ce cadre.

Les tâches à ne pas confier à Cloud

Certaines tâches peuvent bénéficier d’un assistant IA, mais ne devraient pas quitter votre environnement local.

• Dépendance à des fichiers locaux non commités : Cloud ne voit que l’état checkout depuis le dépôt distant.
• Dépendance à une session navigateur ou à un dev server local : le conteneur Cloud n’accède pas automatiquement à votre Chrome, à localhost ni à vos applications de bureau.
• Besoin de secrets de production pendant l’agent phase : les secrets ne doivent pas être exposés à l’agent loop.
• Gros refactoring flou : sans commande de validation, Cloud ne fait que déplacer l’incertitude plus loin.
• Décision produit ou arbitrage d’équipe : Codex peut aider à analyser, mais il ne devrait pas réécrire toute la direction.

Mon réflexe : la première Cloud task doit rester petite. Si vous ne pouvez pas écrire “lancez cette commande pour savoir que c’est fini”, la tâche n’est pas prête pour Cloud.

Avant de lancer une Cloud task, rendre l’environment capable de reproduire le dépôt

Le cycle d’exécution d’une Cloud task

Une Cloud task suit grossièrement cet ordre :

1. Créer un container distant.
2. Checkout le branch ou commit SHA sélectionné.
3. Exécuter le setup script ; si un cached container est restauré, exécuter éventuellement le maintenance script.
4. Appliquer la politique réseau.
5. Laisser l’agent lire les fichiers, modifier le code, lancer des vérifications et tenter la validation dans une terminal command loop.
6. Renvoyer une answer, un summary et un diff ; vous pouvez ensuite poser une question de suivi ou créer un PR.

Beaucoup d’échecs Cloud ne viennent pas d’un agent incapable d’écrire du code. L’environnement ne reproduit simplement pas le dépôt : dépendances impossibles à installer, base de test absente, lockfile incompatible avec le runtime, ou setup script qui suppose un fichier présent seulement sur votre machine.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

setup script, maintenance script et cache

Le setup script doit faire passer le conteneur de “checkout tout frais” à “commande de validation exécutable”. Un exemple minimal peut rester court :

pnpm install
pnpm run typecheck
pnpm test -- --runInBand

Ce n’est pas un modèle universel. C’est surtout un rappel : le Cloud environment doit savoir installer les dépendances, préparer l’environnement de test et lancer au moins une vérification capable de révéler le problème.

Le setup contient souvent :

• Installer les dépendances, linters, formatters, typecheckers et test tools.
• Initialiser une base de test ou générer des substituts sûrs de configuration locale.
• Préparer une authentification ponctuelle pour l’installation de packages privés.
• Placer les valeurs non sensibles persistantes dans environment settings, plutôt que de compter sur un export temporaire dans le script.

Le cache réduit le temps d’installation répétée des dépendances, mais ajoute aussi une couche à vérifier en diagnostic. Un changement de setup script, maintenance script, env vars ou secrets invalide le cache et relance un setup frais. Si les dépendances se comportent soudain différemment, reset le cache est aussi une piste raisonnable.

Secrets, variables d’environnement et réseau : trois endroits où l’on se trompe facilement

Le cycle de vie des secrets et environment variables

La grande différence entre secrets et environment variables n’est pas le nom. C’est le moment où ils sont visibles.

Les secrets conviennent à la phase de setup, par exemple pour installer des dépendances privées ou récupérer des packages internes. Ils doivent être retirés avant l’agent phase. En clair, ne concevez pas une Cloud task qui oblige l’agent à lire un token de production pendant qu’il modifie le code.

Les environment variables restent disponibles pendant toute la tâche. Elles conviennent mieux aux valeurs non sensibles comme NODE_ENV=test, une API base URL publique ou un feature flag.

N’activer agent internet access que si la tâche en a besoin

Le setup script peut utiliser Internet pour installer des dépendances, mais l’agent phase n’a pas d’accès réseau par défaut. Ce choix par défaut compte, car le risque change dès que l’agent lit des pages ou API externes.

Si vous devez activer agent internet access, faites-le de façon conservatrice :

1. Autoriser des domaines précis, au lieu d’ouvrir tout Internet.
2. Limiter les HTTP methods quand c’est possible, par exemple à GET, HEAD et OPTIONS.
3. Ne pas laisser l’agent lire, concaténer ou téléverser des fichiers sensibles.
4. Écrire exactement quels faits doivent être vérifiés par le réseau, pour éviter que l’agent explore librement.

Les risques courants sont prompt injection, exfiltration de code ou de secrets, téléchargement de dépendances malveillantes et problèmes de licence. Ouvrir un réseau unrestricted pour gagner une étape est rarement un bon compromis.

Écrire le prompt Cloud comme un issue

Un modèle de prompt directement utilisable

Un prompt Cloud ne doit pas être un souhait. Il doit ressembler à un petit GitHub issue : objectif, contexte, périmètre, environnement, validation et conditions d’arrêt.

Goal: Fix the failing webhook.test.ts test in GitHub Actions.
Context: The failure log is below; the relevant code is probably in src/webhooks/ and tests/webhooks/.
Scope: Only fix Stripe webhook signature verification. Do not change the payment public API or refactor the test framework.
Environment: The Cloud environment has pnpm dependencies installed. Please run pnpm test tests/webhooks/webhook.test.ts first.
Done when: The target test passes; list changed files, commands you ran, checks you did not run, and risks I need to confirm manually.
Stop if: You need to add a new secret, change the database schema, modify shared/http-client.ts, or cannot reproduce the failure.

Le format n’est pas l’essentiel. L’essentiel est de donner à Codex des limites qu’il peut respecter. Plus la Cloud task ressemble à un issue, plus elle a de chances de rendre un diff relisible.

Stop if vaut mieux que “sois prudent”

“Sois prudent” reste trop abstrait. L’agent ne sait pas toujours où commence la sortie de route. Stop if transforme le risque en conditions concrètes.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Vous pouvez écrire :

• Stop if you need to add a new secret.
• Stop if you need to change the database schema.
• Stop if you must touch the shared auth middleware.
• Stop if the target test cannot be reproduced.
• Stop if the task requires broad renaming or file migration.

Avec ce cadre, la Cloud task a plus de chances de s’arrêter et d’expliquer le risque, au lieu d’élargir le diff.

Une fois la Cloud task terminée, lire le summary, le diff et le journal de commandes

Quand relancer une question, quand ouvrir un PR

Quand Cloud annonce la fin, ne vous arrêtez pas à “done”. Lisez d’abord quatre choses :

1. Le summary reformule-t-il correctement l’objectif et les changements ?
2. Le diff reste-t-il dans le scope ?
3. Le journal de commandes contient-il le test, lint ou typecheck demandé ?
4. Les vérifications non lancées et les risques à confirmer manuellement sont-ils clairement listés ?

Si le diff touche des fichiers hors scope, demandez d’abord :

The diff touches shared/http-client.ts, which was outside scope. Explain why it was necessary. If not necessary, revert that part and keep the webhook fix minimal.

Si le test cible n’a pas été lancé, demandez-le d’abord :

You did not run the target test. Run pnpm test tests/webhooks/webhook.test.ts and summarize the result before opening a PR.

N’avancez vers un PR que lorsque le périmètre des changements est clair, que la commande de validation est crédible et que les risques restants sont nommés.

Que vérifier lors d’une reprise locale

Les deux chemins sont possibles :

• Petit changement : Create PR, puis GitHub review, CI et processus d’équipe.
• Changement plus risqué : check out locally, puis validation avec vos outils locaux, le Codex app review pane ou l’IDE.

Au minimum, vérifiez ceci lors de la reprise locale :

• git status est-il clean, ou êtes-vous sur un branch / worktree isolé ?
• Le diff ne contient-il que l’objectif de la Cloud task ?
• Le test cible, lint et typecheck passent-ils aussi en local ?
• .env*, secrets, CI config, lockfiles ou generated files ont-ils changé ?
• Cette leçon doit-elle devenir une règle dans AGENTS.md ?

Un Cloud diff n’est pas un bouton merge. C’est une tentative distante qui vous revient pour revue.

@codex review dans GitHub : une deuxième porte, pas une autorisation de merge

Déclenchement manuel et automatic reviews

Dans un GitHub PR où Codex Cloud et Code review sont configurés, un commentaire suffit à lancer la review :

@codex review

Vous pouvez aussi la cibler :

@codex review for security regressions

Codex review lit le PR diff, suit les consignes du AGENTS.md le plus proche des fichiers modifiés et se concentre par défaut sur les problèmes à forte priorité. Une équipe peut aussi activer automatic reviews pour lancer la revue quand un PR est opened for review.

Mais automatic review ne veut pas dire automatic merge. Cela peut faire remonter plus vite des problèmes de type P0/P1, sans remplacer le business owner, la CI ni le jugement humain final.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Si la review trouve un problème, vous pouvez demander à Codex de le corriger à partir du PR context, par exemple avec @codex fix the P1 issue. Cela lance un flux Cloud task, et le diff obtenu doit encore être relu.

Si @codex ne répond pas, diagnostiquer dans l’ordre

Ne republiez pas le même commentaire plusieurs fois dans le PR. Vérifiez d’abord :

1. Le repository a-t-il Codex Cloud configuré ?
2. Code review est-il activé pour ce repository dans Codex settings ?
3. Le commentaire contient-il exactement @codex review ?
4. automatic review est-il activé, et l’événement correspond-il ?
5. GitHub app / repository permission permet-il de lire le PR diff, les commentaires et le push branch ?
6. workspace/admin policy, GitHub Enterprise ou private repo access imposent-ils une restriction ?
7. Les usage limits sont-ils atteints, surtout parce que les code review limits peuvent différer de l’usage chat ordinaire ?

Si Cloud tasks, commentaires de review et autres commentaires @codex se comportent différemment, notez la task, le commentaire, le repository et l’heure avant de contacter le support officiel ou votre workspace admin.

Remote devbox / SSH host n’est pas Cloud

Quand utiliser une remote connection

Certaines tâches ne vont ni bien en Local ni bien en Cloud : le projet vit déjà sur une devbox, une machine GPU, un réseau interne ou un enterprise remote development host.

La distinction est simple :

• Codex Cloud : OpenAI managed / configured cloud environment, checkout un dépôt GitHub, adapté aux tâches de dépôt et aux workflows PR loin de votre machine.
• Remote connection / SSH host : la Codex app se connecte à votre remote host et utilise les files, credentials, permissions, plugins, browser setup et local tools de cette machine.

Si la tâche a besoin d’un service interne, d’un GPU, d’une base de données distante ou d’outils déjà configurés sur une devbox, une remote connection est plus proche du vrai environnement. Sa frontière de sécurité change aussi : les permissions, credentials et tools disponibles sur ce host deviennent la frontière donnée à Codex.

La configuration conservatrice consiste à utiliser des trusted SSH keys et des least-privilege accounts, à ne pas exposer app-server transport à Internet public, et à privilégier VPN ou mesh networking pour traverser les réseaux.

Une SOP Codex Cloud conservatrice

Pour une première mise en place de Codex Cloud, suivez cette séquence :

1. Choisir une petite tâche avec un état de dépôt reproductible, pas un grand refactoring.
2. Configurer le Cloud environment du repository.
3. Écrire un setup script pour rendre l’installation des dépendances et le check cible répétables.
4. Mettre uniquement les valeurs sensibles de setup phase dans secrets ; placer la configuration non sensible dans env vars.
5. Garder agent internet access désactivé par défaut ; si nécessaire, allowlist seulement les domaines et methods requis.
6. Écrire le task prompt comme un issue : Goal, Context, Scope, Environment, Done when, Stop if.
7. Pendant l’exécution, regarder plan, commands et failures.
8. Après la fin, lire summary, diff, test results et skipped checks.
9. Créer un PR pour une petite modification ; check out locally d’abord pour les changements plus risqués.
10. Utiliser @codex review dans le PR comme deuxième contrôle.
11. Laisser les humains, la CI et le processus d’équipe décider du merge.
12. Transformer les leçons de review répétées en règles dans AGENTS.md.

Ce qui rend Cloud fiable, ce n’est pas un niveau d’automatisation plus élevé. C’est la présence d’une frontière claire à chaque étape : l’environment reproduit le repo, le prompt est exécutable, le diff est reviewable, et la trace de review est vérifiable. C’est ainsi que l’on confie une exigence précise à un agent cloud, au lieu d’envoyer l’incertitude plus loin.