Aller au contenu

Pourquoi l'agent pousse lui-même, et ce qui le retient

Cette page explique une décision d'infrastructure de dev qui élargit le modèle de menace : l'agent de développement a gagné la capacité d'écrire sur origin, et celle d'écrire dans l'espace de travail du dépôt principal. Elle dit pourquoi ces deux capacités ont été ouvertes ensemble, ce qui a été abandonné en échange, et ce qui reste pour tenir la ligne.

Pour les gestes, voir Pousser sur GitLab depuis un worktree. Pour la liste des variables qui portent le dispositif, voir Git dans le conteneur (dev local).

Une garantie qui n'était pas une décision

Le projet a longtemps tenu un invariant confortable : le ship est relu par un humain avant publication. Un lot terminé, revu et testé attendait un geste sur l'hôte pour rejoindre GitLab.

Le confort venait de ce que personne n'avait à l'appliquer. L'invariant n'était pas une règle qu'on faisait respecter, c'était une impossibilité technique : le remote était en SSH, openssh-client absent de l'image du conteneur, et le port 22 non tunnelable par le proxy d'allowlist qui filtre toute la sortie réseau. L'agent ne pouvait pas pousser, quoi qu'il tente.

Cette situation produisait une asymétrie déroutante : glab fonctionnait — il parle HTTPS et token à l'API — donc l'agent pouvait créer une merge request, la commenter, fermer une tâche… mais pas pousser la branche qu'il venait d'écrire. Le seul maillon qu'un run autonome ne pouvait pas franchir était le dernier.

Le prix était mesurable : chaque lot s'arrêtait au ship, et l'enchaînement de lots que le skill implementer-lot sait faire s'interrompait à chaque merge request.

Ce qui a été tranché

Le remote de push bascule en HTTPS + jeton dans le conteneur. L'invariant « le ship est relu par un humain avant publication » est donc explicitement abandonné.

Il faut le dire dans ces termes, plutôt que de laisser croire qu'il tient encore. Une garantie qui reposait sur un accident de configuration disparaît avec lui — et une garantie qu'on croit tenir alors qu'elle est tombée est pire qu'une garantie qu'on n'a jamais eue.

Ce qui subsiste, en revanche, est de nature différente :

  • la règle projet « actions à effet remote = script obligatoire » reste la règle. Elle n'a jamais eu pour rôle d'empêcher techniquement le push : elle sert à relire le payload — message de commit, corps de merge request, body d'appel API — avant qu'il ne soit publié, parce qu'un commentaire ou une MR publiés restent visibles même supprimés ensuite. Elle garde un pendant exécutable — .claude/settings.json dénie git push au main Claude, qui passe donc par un script — mais un script est du texte que l'agent écrit lui-même : ce qui tenait la règle, c'était l'impossibilité de pousser, et c'est cette part-là qui repose maintenant sur la discipline. Source de vérité : .claude/skills/_shared/actions-remote-scripts.md ;
  • deux garde-fous exécutables, qui n'existaient pas avant, prennent le relais sur ce qui compte vraiment.

Deux garde-fous, deux natures

La tentation serait de présenter le hook pre-push comme la nouvelle barrière. Il ne l'est pas, et le prétendre serait la même erreur que de croire l'ancien invariant toujours debout.

Garde-fou Nature Ce qu'il tient
Hook pre-push (infra/git-hooks/pre-push) côté client, dans le conteneur l'accident : git push --tags par réflexe, HEAD:main par distraction
Branches protégées GitLab côté serveur, hors du dépôt la barrière réelle : elle s'applique quoi que fasse le client

Un hook git est contournable d'un mot — --no-verify, ou une réécriture de core.hooksPath. Il empêche l'accident, jamais la malveillance. C'est une raison de l'écrire, pas une raison de s'en contenter : les accidents sont précisément ce qui arrive dans un run automatisé, où personne ne relit la commande avant qu'elle parte.

Deux propriétés du hook méritent d'être connues plutôt que découvertes, et elles sont documentées comme telles dans la how-to :

  • il est versionné, donc absent d'un worktree resté sur une branche antérieure — et git saute un hooksPath inexistant en silence ;
  • il est fail-closed : si sa bibliothèque de décision est illisible ou incomplète, il refuse le push au lieu de le laisser passer. Un garde-fou qui remplace un invariant abandonné ne peut pas se permettre de tomber en mode ouvert.

Pourquoi les tags sont refusés en bloc

Le hook refuse les branches d'intégration par motif, mais tout tag sans exception. Ce n'est pas de la prudence de principe : dans ce projet, taguer déploie en production — la pipeline construit l'image, la pousse, la signe et crée la release sur $CI_COMMIT_TAG. Un git push --tags, c'est-à-dire le réflexe même, publierait une release.

L'agent n'a par ailleurs aucun tag légitime à pousser : la procédure du projet crée le tag côté serveur via l'API GitLab (cf. Créer un tag de release). Refuser en bloc ne coûte donc rien et ferme un chemin dont le pire cas est un déploiement non voulu.

L'autre moitié : un espace de travail partagé

Le second volet de la même décision est moins spectaculaire et pose pourtant le même genre de question.

var/ est gitignoré. Chaque worktree avait donc son propre var/claude/, vide à la création — alors que ce dossier est exactement la mémoire de travail des skills : cadrage d'étape, specs de lots, scripts de ship déjà écrits, rapports. Un worktree neuf redémarrait à froid, et un worktree détruit emportait le travail du cycle avec lui.

La correction consiste à faire pointer le var/claude d'un worktree sur celui du dépôt principal, monté au même chemin absolu dans le conteneur.

Le « même chemin absolu » est la contrainte qui commande toute la conception, et elle mérite d'être expliquée parce qu'un bind plus simple semble évident : <principal>/var/claude:/app/var/claude n'existerait que dans le conteneur. Or ce dossier est lu des deux côtés — les scripts de ship, les vérifications de DoD et le rechargement du pare-feu tournent depuis l'hôte, sur des fichiers écrits depuis le conteneur. Côté hôte, <worktree>/var/claude serait resté le dossier local vide : les deux vues auraient divergé en silence, c'est-à-dire exactement le symptôme qu'on corrigeait. Le montage au même chemin des deux côtés est la technique que le projet emploie déjà pour le git common dir, pour la même raison.

Le dépôt principal, lui, n'a rien à recevoir : son bind .:/app lui donne déjà ce dossier, il en est la source. C'est ce qui évite le piège classique de ce genre de réconciliation — le dépôt principal n'est pas un worktree et ne reçoit jamais de castor wt:up.

Tout ce qui est dans var/claude n'est pas partageable

Partager la mémoire de travail est un gain ; partager l'état d'une session en cours serait une régression. Deux agents travaillant en parallèle dans deux worktrees s'écraseraient mutuellement leur checklist de clôture, leur quota de fichiers PHP, leur compteur de blocage et leur verdict de revue. On aurait échangé une perte de contexte contre une corruption d'état — ce qui est pire, parce qu'une perte de contexte se voit et qu'une corruption d'état, non.

D'où la ligne de partage : ce qui décrit le travail est commun, ce qui décrit une session est namespacé par worktree, sous var/claude/.session/<worktree>/. Le détail des fichiers concernés est en référence : Hooks Claude Code.

La résolution du namespace retombe sur main — le dépôt principal — dès que l'identifiant de worktree est absent ou douteux. Elle valide la valeur avant d'en faire un composant de chemin : un identifiant contenant .. s'échapperait du dossier de session pour aller écrire chez un voisin, c'est-à-dire produire précisément la corruption que le namespace existe pour empêcher.

L'élévation à assumer

Le partage ouvre un canal d'écriture d'un worktree vers l'espace du dépôt principal — et var/claude/*.sh est justement où vivent les scripts que l'humain lance ensuite depuis l'hôte, ceux-là mêmes que le hook guard-rm autorise à supprimer sans confirmation.

C'est le vrai coût de sécurité de ce volet, et il a été arbitré avec le volet push plutôt qu'en passant. Il est consigné là où le contrat de confinement le rend vérifiable : .claude/skills/_shared/confinement.md, limite connue de C8 n° 3. L'invariant C8 lui-même n'est pas violé — il porte sur le système de fichiers des autres worktrees, et aucun arbre de travail ne devient visible — mais une garantie qu'on n'écrit pas est une garantie que personne ne vérifie.

Trois options écartées

Elles reviendraient toutes à élargir l'accès du conteneur plutôt qu'à le cibler, et il vaut la peine de dire pourquoi :

  • installer un client SSH dans l'image — cela rouvrirait un transport que le proxy d'allowlist ne filtre pas. Le HTTPS, lui, passe par le proxy comme tout le reste ;
  • monter une clé SSH personnelle dans le conteneur — cela donnerait à l'agent l'identité git complète du développeur, bien au-delà de ce dépôt. Le jeton dédié à Kirexo, lui, n'ouvre qu'un projet et se révoque sans conséquence ailleurs (cf. Créer et faire tourner le jeton GitLab de Kirexo) ;
  • versionner var/claude — ce sont des artefacts liés à un ticket précis, périmés dès sa clôture. Un dépôt qui en serait rempli rendrait chaque git status illisible. Ce qu'il fallait, c'est un espace de travail partagé, pas du versionnement.

Une exception, arrachée par une perte : l'outillage de preuve

Tout ce qui vivait dans var/claude n'était pas un artefact de ticket. Les sondes qui prouvent la Definition of Done d'une étape y étaient rangées elles aussi — et quatre d'entre elles ont purement et simplement disparu, sans que rien ne le signale. Elles sont depuis versionnées dans infra/dod/, et jouées par castor dod:check / dod:tls / dod:clean.

L'arbitrage ci-dessus n'est pas renversé pour autant, il est précisé : ce qui atteste d'un run (specs, scripts de ship, rapports, journaux) reste sous var/ ; ce qui permet de refaire le run est versionné. Le raisonnement complet : Une preuve non versionnée n'est pas une preuve.

Voir aussi