Intégration Git et GitHub : faire de Codex un relecteur de PR

📚 Navigation dans la série : Le chapitre précédent [25 · Arborescences de travail Git isolées (Worktrees)] présentait l'isolation des tâches par worktrees pour mener plusieurs développements en parallèle. Ce chapitre déplace le champ d'action de votre terminal local vers les dépôts GitHub : comment intégrer Codex dans vos Pull Requests (PR) pour analyser automatiquement le code, valider les modifications selon vos règles d'équipe et pousser les corrections directement sur la branche. Le chapitre suivant [27 · Automatisation et intégration continue (CI/CD)] étendra cette intégration aux chaînes de CI/CD.

Abordons un cas récurrent de la vie d'équipe. Entre la création d'une Pull Request (PR) et sa validation finale, une part importante du temps est perdue à attendre qu'un collaborateur effectue la revue. Dans les petites structures, les relecteurs (reviewers) étant occupés, une PR peut rester en attente pendant des heures.

Et lorsque la revue a lieu, l'humain a tendance à se focaliser sur des détails cosmétiques (« renommer cette variable », « ajouter un espace ») ; les erreurs critiques — conditions de concurrence complexes, oublis d'authentification ou fuites d'informations confidentielles dans les logs — sont plus difficiles à déceler et faciles à omettre lorsque la fatigue s'installe.

L'intégration GitHub de Codex répond à ce besoin : mentionnez-le par un simple @codex review dans les commentaires d'une PR pour qu'il analyse les modifications, compare le code avec vos règles de développement et signale les risques majeurs directement sous forme de commentaires de ligne. Vous restez dans GitHub, et Codex n'effectue aucune modification finale sans votre accord : il se charge de l'audit, vous validez l'intégration, respectant la séparation des rôles présentée au chapitre 15.

À la fin de ce chapitre, vous aurez en main :

• L'appel du script de relecture avec la commande @codex review et les niveaux de sévérité signalés (P0/P1).
• Le paramétrage de la relecture automatique (Automatic reviews) pour auditer chaque nouvelle PR sans commande manuelle.
• La personnalisation des règles de relecture avec la section Review guidelines du fichier AGENTS.md (sécurité des logs, validation des accès, etc.).
• La correction automatique des bugs identifiés avec la commande @codex fix et les droits d'écriture associés.
• L'audit local en ligne de commande avec la commande slash /review pour analyser les modifications avant publication.
• La distinction entre les tâches automatisables et les actions critiques de validation finale (merge, force-push) qui doivent rester sous votre contrôle exclusif.

⚠️ Précision technique : Les revues déclenchées sur GitHub (@codex review, relecture automatique) reposent sur Codex cloud, ce qui nécessite un abonnement actif et l'autorisation d'accès au dépôt. La commande locale /review s'exécute sur votre machine sans dépendance cloud.

---

01 Distinguer les deux modes de relecture : GitHub vs Console locale

En résumé : l'audit de code s'effectue selon deux flux : l'audit distant sur GitHub (@codex review, exécuté dans le cloud et reporté sur la PR) et l'audit local (commande /review, exécuté sur votre machine en lecture seule).

Analogie : Le correcteur de devoirs. Un correcteur peut corriger votre copie après sa remise officielle (relecture GitHub) ; il peut également s'asseoir à vos côtés pendant votre travail pour signaler les erreurs au fil de l'écriture (relecture locale). Les deux rôles sont utiles, mais diffèrent par le moment d'intervention et la portée des droits.

Les deux flux de Codex s'organisent ainsi :

1. Le flux distant GitHub (cloud) : Saisissez @codex review dans les commentaires d'une PR sur GitHub. Codex lance une instance de traitement dans le cloud, lit les modifications (diff) de la PR, puis publie ses commentaires directement sur les lignes de code concernées. Ce mode s'exécute sur les serveurs d'OpenAI (Codex cloud, voir chapitre 10) et requiert l'activation de l'option Code review dans vos paramètres. 2. Le flux local (CLI) : Saisissez la commande /review dans la console Codex de votre machine. Codex audite la partie de code sélectionnée (modifications courantes, commits spécifiques ou différences de branches) et affiche les points d'amélioration dans votre terminal. Ce mode est strictement en lecture seule et ne modifie pas votre code.

Dimension	Relecture GitHub (@codex review)	Relecture locale (CLI)
Déclenchement	Commentaire de PR sur GitHub	Commande /review en console locale
Environnement	Codex cloud (distant)	Machine de l'utilisateur (local)
Cible	Modifications (diff) de la PR active	Modifications locales, commits ou branches cibles
Restitution	Commentaires et annotations sur la PR GitHub	Rapport d'audit dans la console
Prérequis	Connexion cloud active et accès configuré	Aucun (fonctionne hors ligne)
Écriture de code	Possible via la commande @codex fix	Lecture seule stricte

Ce chapitre présente principalement le flux distant sur GitHub. La commande de relecture locale /review est détaillée à la section 06 comme outil d'audit avant validation.

💡 En résumé : La relecture s'organise en deux voies : le mode GitHub (exécuté sur le cloud, publie ses retours sur la PR) et le mode local (exécuté sur la machine, affiche les alertes en console). Ce chapitre se concentre sur l'intégration GitHub.

---

02 Interroger Codex sur une PR : La commande @codex review

Pour auditer une Pull Request, saisissez le commentaire @codex review dans la zone de discussion de la PR.

La revue de code manuelle est fastidieuse et propice aux oublis de sécurité sous l'effet de la fatigue. Confier la première lecture à une instance d'IA évite de laisser passer des failles de logique évidentes.

Analogie : L'éditeur spécialisé dans la relecture de manuscrits. Avant de soumettre votre texte pour publication, vous le transmettez à un correcteur chargé d'identifier les incohérences ou les fautes de syntaxe. L'éditeur ne modifie pas le style général, mais pointe les passages qui posent problème. Codex joue ce rôle sur votre code : il recherche les anomalies logiques et les failles de sécurité.

Le traitement de la commande s'effectue ainsi :

1. Codex ajoute un emoji 👀 en réaction à votre commentaire pour confirmer la prise en compte du traitement.
2. L'instance cloud démarre, télécharge les modifications de la PR et les compare avec vos règles de développement.
3. Codex publie ses commentaires de relecture sous forme d'annotations sur les lignes de code de la PR.

Une règle d'affichage importante limite le volume des retours :

Sur GitHub, Codex ne signale que les anomalies de niveaux P0 et P1 afin de focaliser la relecture sur les risques majeurs.

Les niveaux de priorité se répartissent ainsi : P0 désigne une anomalie bloquante (faille de sécurité, crash) et P1 un dysfonctionnement important. Codex n'affiche pas de commentaires sur les détails cosmétiques de style (indentation, espacement) pour ne pas polluer l'historique de la PR. Cette restriction permet de se concentrer sur les alertes importantes.

Exemple réel : sur une PR modifiant le traitement des transactions bancaires, la relecture automatique a détecté qu'un appel d'API intermédiaire ne gérait pas le principe d'idempotence, exposant le système à des doubles débits en cas d'appels répétés. Cette anomalie de niveau P1 a pu être corrigée avant l'intégration.

💡 En résumé : Mentionner @codex review dans les commentaires d'une PR déclenche l'audit des modifications. L'analyse se limite aux alertes critiques (P0/P1) pour préserver la lisibilité de la revue.

---

03 Automatiser la relecture sur chaque Pull Request

Pour éviter d'avoir à saisir la commande manuellement, vous pouvez activer la relecture automatique (Automatic reviews).

Analogie : Le passage au contrôle technique obligatoire. Plutôt que de décider d'inspecter un véhicule avant un trajet (audit manuel), le contrôle technique est programmé de façon réglementaire à des jalons fixes. La relecture automatique applique cette politique : chaque dépôt de code fait l'objet d'un audit de sa PR dès sa création.

La documentation officielle détaille l'activation :

Pour auditer automatiquement chaque PR, activez l'option Automatic reviews dans les paramètres de votre compte Codex. Dès qu'une PR est initialisée, Codex l'analyse sans exiger de mention @codex review.

L'activation s'effectue dans les paramètres de configuration en ligne (sur chatgpt.com dans la section Codex → Settings → Code review).

Une fois l'option active, la création d'une PR ou l'ajout de commits déclenche l'audit de façon transparente.

Politique d'usage conseillée :

• Dépôts de code collaboratifs d'équipe : Activez l'option automatique pour garantir que tout code partagé fait l'objet d'un premier audit de sécurité.
• Projets personnels ou expérimentaux : Privilégiez l'appel manuel @codex review pour limiter la consommation de ressources sur des modifications mineures.
• Modifications critiques spécifiques : Même si l'option automatique est active, vous pouvez demander une relecture ciblée en saisissant par exemple @codex review for security regressions (relecture orientée sécurité).

Caractéristique	Appel manuel @codex review	Relecture automatique
Déclenchement	Commentaire textuel de l'utilisateur	Création ou mise à jour de la PR
Garantie d'audit	Repose sur l'action de l'utilisateur (risque d'oubli)	Systématique pour toutes les PR du dépôt
Usage type	Projets personnels, analyses ponctuelles	Dépôts d'équipe, processus de CI

💡 En résumé : L'activation de la relecture automatique (option Automatic reviews dans les paramètres) lance l'audit de toute nouvelle PR de manière systématique, sans action manuelle.

---

04 Personnaliser les critères d'audit dans le fichier AGENTS.md

Vous pouvez adapter les critères d'audit de Codex aux règles d'écriture de votre équipe en déclarant vos consignes dans le fichier AGENTS.md.

Les règles d'audit se rédigent sous une section dédiée nommée Review guidelines (Consignes de relecture) au sein de votre fichier AGENTS.md.

Analogie : La charte qualité affichée dans un atelier. Le technicien applique les normes générales de sa profession. La charte qualité détaille les contrôles spécifiques à l'atelier : « Vérifier le serrage au couple indiqué, valider la présence de l'étiquette de traçabilité ». Le fichier AGENTS.md est cette charte qualité rédigée pour Codex.

Exemple de consignes à déclarer dans le fichier AGENTS.md à la racine de votre projet :

## Review guidelines

- Don't log PII (Personally Identifiable Information).
- Verify that authentication middleware wraps every route.

Le fait d'inscrire ces lignes indique à Codex de vérifier systématiquement que le code modifié ne consigne pas d'informations confidentielles dans ses journaux de logs, et que les nouvelles routes intègrent le middleware d'authentification.

Le système applique la règle de proximité :

Codex lit les consignes de la version de AGENTS.md la plus proche du fichier de code analysé. Vous pouvez placer des fichiers AGENTS.md spécifiques dans vos sous-dossiers pour appliquer des règles d'audit restrictives sur des modules critiques.

Exemple de fichier src/payment/AGENTS.md (règles de transaction) :

## Review guidelines

- Utilisez le type Decimal pour tout calcul financier (interdire le type float).
- Validez la présence d'une clé d'idempotence pour toute transaction d'écriture.

Lors de l'audit d'un fichier du dossier src/payment/, Codex applique ces consignes d'écriture en priorité.

Vous pouvez également cibler une relecture sur un aspect précis lors d'un appel manuel, par exemple : @codex review for security regressions (recherche de failles de sécurité).

💡 En résumé : Le bloc Review guidelines de AGENTS.md définit vos critères de relecture. Codex applique ces consignes selon la règle de proximité, vous permettant de surcharger les contrôles sur les dossiers sensibles.

---

05 Corriger les anomalies automatiquement : La commande @codex fix

Si une anomalie est signalée par Codex sur une ligne de code, vous pouvez lui demander de la corriger directement en saisissant un commentaire.

Analogie : Le relecteur qui applique ses propres corrections. Au lieu de se limiter à signaler une faute sur un document, le relecteur réécrit le paragraphe concerné et valide la modification. La commande @codex fix délègue cette action de réécriture à l'IA.

Saisissez la commande suivante dans le fil de discussion de l'anomalie :

@codex fix the P1 issue

La documentation officielle décrit le comportement de cette commande :

Codex utilise la Pull Request active comme contexte pour lancer une tâche cloud, puis pousse les modifications corrigées directement sur la branche du projet (si les droits d'écriture lui sont accordés).

Deux paramètres clés régissent cette commande :

1. Lancement d'une tâche cloud : La modification n'est pas rédigée à la volée dans la discussion. Codex démarre une instance de traitement isolée (Codex cloud, voir chapitre 10) pour analyser le code, appliquer la correction et vérifier sa compilation.
2. Droits d'écriture requis : Le rapatriement de la correction sur votre branche GitHub exige que vous ayez accordé les droits de modification à Codex dans les paramètres d'accès du dépôt. Si Codex n'a qu'un accès en lecture seule, il vous affichera la proposition de correction dans le chat sans pouvoir modifier la branche.

Note de syntaxe concernant les mentions @codex :

• Si le message contient le mot review (ex: @codex review) : Codex exécute uniquement une tâche d'audit (sans modification de code).
• Si le message contient d'autres instructions (ex: @codex fix the P1 issue ou @codex ajoute les tests pour cette fonction) : Codex exécute une tâche d'écriture globale sur le dépôt.

Règle de sécurité de livraison : la commande @codex fix pousse ses modifications sur votre branche de PR. La validation finale (le merge) dans votre branche principale doit rester sous votre contrôle exclusif. N'autorisez pas un agent d'IA à valider directement la fusion dans vos branches de production.

💡 En résumé : La commande @codex fix lance une tâche cloud pour corriger une anomalie et pousse les modifications sur votre branche de PR si Codex dispose des droits d'écriture. La fusion finale (merge) reste à votre charge.

Ce schéma résume les étapes d'audit : lors de la création d'une PR, l'audit est initié (automatiquement ou via @codex review). Codex cloud télécharge le code, applique les règles de proximité du fichier AGENTS.md local, puis publie ses commentaires P0/P1. La saisie de la commande @codex fix démarre une instance d'écriture qui corrige la branche et relance une boucle d'audit.

---

06 Relecture en console locale avant publication

Avant de pousser vos modifications sur GitHub et de créer une PR, vous pouvez effectuer un audit en lecture seule sur votre machine avec la commande /review.

Analogie : L'auto-correction avant le rendu d'un travail. Cette démarche évite d'exposer des erreurs de syntaxe simples dans votre historique partagé en corrigeant les anomalies localement.

Saisissez la commande suivante dans votre terminal Codex :

/review

L'interface console affiche un menu de sélection regroupant plusieurs options d'audit (ce traitement s'exécute en lecture seule et ne modifie aucun fichier) :

• Review against a base branch (Comparer avec une branche d'origine) : Compare votre code avec une branche de référence (ex: main) pour auditer vos modifications avant de créer la PR.
• Review uncommitted changes (Auditer les modifications non validées) : Analyse l'état courant de vos fichiers (modifications indexées ou non).
• Review a commit (Auditer un commit) : Analyse les modifications apportées par un commit spécifique d'après son identifiant (hash).
• Custom review instructions (Consignes d'audit personnalisées) : Saisie d'une consigne d'audit spécifique pour ce traitement.

Vous pouvez déclarer un modèle d'IA plus performant pour cette tâche de relecture en renseignant la clé review_model dans votre configuration globale config.toml (permettant d'utiliser un modèle rapide pour le code au quotidien et un modèle d'analyse poussé pour les revues).

Enchaînement de travail recommandé :

1. Appliquez vos modifications locales.
2. Lancez /review et sélectionnez Review uncommitted changes pour auditer vos fichiers.
3. Corrigez les anomalies signalées dans votre éditeur.
4. Validez vos modifications et créez votre PR sur GitHub.

💡 En résumé : La commande locale /review audite votre code en console en lecture seule selon plusieurs filtres de comparaison (commits, branches, modifications courantes), permettant de nettoyer le code avant sa publication.

---

07 Intégration de l'utilitaire GitHub CLI (gh)

Pour permettre à l'application de bureau Codex (ou aux extensions d'éditeurs) d'afficher le contexte et les commentaires des PR, l'installation de l'outil GitHub CLI (gh) est nécessaire.

Analogie : Le badge d'accès aux archives de l'entreprise. Sans badge, l'assistant sait qu'un dossier de modification existe, mais ne peut pas lire les rapports d'échanges ou les annotations associées. L'authentification via gh lui fournit l'accès à ces informations.

La documentation officielle le précise :

L'installation et l'authentification de l'outil GitHub CLI (gh) via la commande gh auth login sont nécessaires pour permettre à Codex de charger le contexte des PR, les commentaires de relecture et la liste des fichiers modifiés. Si gh n'est pas configuré, les détails des PR ne s'afficheront pas dans vos panneaux d'édition.

Commandes d'installation selon votre système d'exploitation :

# Pour macOS (via Homebrew)
brew install gh

# Pour Windows (via winget)
winget install --id GitHub.cli

# Après installation, authentifiez votre session :
gh auth login

Une fois l'authentification effectuée, l'application de bureau Codex affiche le fil des commentaires de la PR au sein de son panneau de revue, vous permettant de demander des corrections en langage naturel et de valider les modifications de fichiers d'un clic avant de les pousser.

Rappel de sécurité concernant le traitement des données (chapitre 16) : les commentaires et historiques de PR lus par Codex constituent des données externes. Soyez vigilant si un commentaire de relecture contient des instructions suspectes demandant l'exécution de scripts ou de connexions réseaux, afin de vous prémunir des injections de requêtes (prompt injection).

💡 En résumé : L'authentification de l'utilitaire gh est requise pour charger l'historique et les commentaires des PR au sein de l'application de bureau. L'outil s'installe via Homebrew ou winget et s'active avec gh auth login.

---

08 Les règles de sécurité à respecter : Ne pas déléguer la fusion finale

Cette section rappelle les limites de droits à appliquer aux outils d'IA (faisant écho aux chapitres 15 et 16).

Analogie : La distinction entre la rédaction d'un acte juridique et sa signature. Un juriste rédige, valide et corrige les clauses d'un contrat (rôle d'analyse). La signature finale qui engage l'entreprise doit être apposée par le responsable légal (rôle décisionnel). Git applique cette séparation sur ses fusions de branches.

Sécurité des actions de commits :

Type d'action	Niveau de risque	Recommandation
Relecture de code, détection d'anomalies (lecture seule)	Modéré	Délégable en confiance à Codex
Correction de code sur une branche de Pull Request	Moyen	Autorisé si vous validez le code modifié avant intégration
Fusion de la PR dans la branche principale (main/master)	Élevé	À réaliser exclusivement par un humain (validation finale)
Modification forcée de l'historique (git push --force)	Élevé	Interdit aux outils d'IA (risque de perte de commits)

Règles de sécurité de votre dépôt :

1. Bloquer l'action de merge automatique : Ne configurez pas de scripts automatiques autorisant Codex à valider la fusion d'une PR dans vos branches de production. Cette décision finale exige une relecture et validation humaine. 2. Exclure la commande de force-push : La modification forcée de l'historique Git (git push --force) comporte un risque d'écrasement des commits de vos collaborateurs. Réalisez ces opérations d'administration manuellement en vérifiant les branches cibles.

Cette approche correspond à la configuration par défaut de Codex, qui s'exécute par défaut en mode lecture seule (read-only) pour limiter les risques système. Conservez cette logique de restriction sur vos branches distantes.

💡 En résumé : Déléguez l'audit et les propositions de correction à Codex. Conservez la validation de la fusion (merge) et l'usage des commandes d'administration Git (git push --force) sous votre contrôle humain exclusif.

---

09 Synthèse des rôles de relecture

Le schéma d'intégration de Codex comme relecteur de code s'organise ainsi :

Ce schéma résume le flux d'intégration : les phases d'analyses locales (commande /review avant publication) et distantes (commandes @codex review et corrections de code via @codex fix sur la PR) sont déléguées à Codex pour identifier les anomalies. La validation finale de la fusion (merge) dans la branche principale ou l'usage des commandes de force-push restent confinés dans l'espace de décision de l'utilisateur humain.

Cette organisation combine la vitesse d'analyse de l'IA avec la sécurité décisionnelle de l'humain.

💡 En résumé : L'humain pilote la fusion finale et gère l'historique Git. Codex se charge des revues préliminaires, des détections de failles logiques et de la proposition de corrections sur les branches de travail.

---

10 En pratique : Exécuter un audit local avec /review

Bien que la relecture sur GitHub exige une connexion cloud active, vous pouvez tester le fonctionnement de l'audit local /review hors ligne sur votre machine.

Étape 1 : Initialiser le dépôt de test

Créez un dossier temporaire, configurez le dépôt Git local et commitez un premier script contenant volontairement une vulnérabilité SQL :

mkdir review-demo
cd review-demo
git init
printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n' > app.py
git add app.py
git commit -m "feat: initialisation du module get_user"

Étape 2 : Ajouter une modification non validée

Modifiez le script en ajoutant une nouvelle fonction présentant la même vulnérabilité d'écriture (sans indexer ni valider le fichier) :

printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n\ndef delete_user(uid):\n    db.execute("DELETE FROM users WHERE id=" + uid)\n' > app.py

Le fichier app.py présente désormais une modification non commitée.

Étape 3 : Ouvrir la session et lancer l'audit

Démarrez Codex dans le dossier :

codex

Lancez l'utilitaire d'audit :

/review

Comportement avant-attendu : Le menu de sélection de comparaison s'affiche. Sélectionnez l'option Review uncommitted changes (Auditer les modifications non validées) et validez.

Étape 4 : Analyser le rapport de relecture

Comportement attendu : Codex analyse le diff des modifications de app.py. L'assistant affiche une alerte de priorité haute signalant le risque d'injection SQL sur la fonction delete_user, avec une recommandation de passage à une réquête préparée. Le fichier app.py est resté inchangé en local.

Étape 5 : Supprimer le répertoire de test

Fermez la session Codex et supprimez le dossier :

cd ..
rm -rf review-demo

Cet exercice valide la mise en œuvre de la revue locale avant commit.

💡 En résumé : L'exercice montre comment lancer la commande /review sur des modifications non validées, valider la détection d'une injection SQL par le modèle et s'assurer du respect de la lecture seule en local.

---

11 Résumé

Ce chapitre a présenté l'intégration de Codex avec Git et GitHub pour auditer les Pull Requests et simplifier le travail de revue.

Voici les points clés à retenir :

| Thématique | Règle de fonctionnement | |---|---|---| | Utilité | Automatise la revue de code et détecte les failles logiques dans les Pull Requests. | | Modes | GitHub Cloud via la commande @codex review ou Console locale via la commande /review. | | Priorités | Les retours GitHub se limitent aux alertes critiques (P0/P1) pour éviter la pollution de l'historique. | | Règles | Rédigées sous le bloc Review guidelines du fichier AGENTS.md (soumises à la règle de proximité). | | Corrections | La commande @codex fix corrige la branche de PR si les droits d'écriture sont accordés. | | Dépendance | GitHub CLI (gh) est requis pour charger le contexte de PR au sein de l'application de bureau. | | Sécurité | Les fusions (merge) et les commandes de force-push doivent être exécutées exclusivement par l'humain. |

Vous êtes désormais en mesure de distinguer les modes d'audit locaux et cloud, d'appeler l'analyse sur une PR avec @codex review, d'activer l'audit automatique dans vos paramètres de compte, de consigner des règles de relecture spécifiques dans le fichier AGENTS.md, d'appliquer des corrections automatiques sur vos branches de PR, de configurer l'accès via l'utilitaire gh, et d'appliquer les consignes de sécurité indispensables concernant la validation des fusions.

---

Le chapitre suivant 27 · Automatisation et intégration continue (CI/CD) présente l'intégration dans vos chaînes de déploiement : comment utiliser Codex au sein de GitHub Actions pour corriger des erreurs de compilation ou de tests de façon automatisée sans surveillance humaine ? Nous verrons comment mettre en œuvre des flux de correction automatiques.

---

Lectures recommandées

• Définir des compétences réutilisables (Skills)
• Exercice pratique de programmation
• Extensions d'éditeurs de code (IDE)