Pousser sur GitLab depuis un worktree¶
Vous êtes développeur·se sur Kirexo, vous travaillez dans un worktree (ou dans le dépôt principal), et vous voulez pousser votre branche sur GitLab. Cette recette explique comment pousser depuis le conteneur, ce que le garde-fou pre-push refuse, et quoi faire quand l'authentification échoue.
Prérequis¶
- Une stack démarrée :
castor wt:up 185(cf. Créer et détruire un worktree), oucastor docker:updans le dépôt principal. Entrer parcd <chemin du worktree>puiscastor wt:shellsuffit : la cible démarre la stack elle-même si elle ne répond pas. - Le jeton GitLab dédié renseigné dans
~/.kirexo/secrets/gitlab-tokensur l'hôte, au format dotenv (GITLAB_TOKEN=glpat-…), avec le scopewrite_repository. Procédure complète : Créer et faire tourner le jeton GitLab de Kirexo. - Un conteneur créé après la mise en place de la configuration git par l'environnement. Si le vôtre est plus ancien, recréez-le :
castor wt:up <ticket>côté hôte.
Pousser depuis le conteneur¶
C'est le geste nominal. Rien à configurer : la configuration git est injectée dans l'environnement du conteneur php, pas écrite dans le dépôt.
# Dans le conteneur
git status
git commit -m "feat(worktree): ajoute la clé partagée"
git push origin ticket-185
Trois obstacles historiques ont été levés, tous par des variables d'environnement posées dans le service php de compose.override.yaml — donc valables pour le dépôt principal comme pour les worktrees :
| Ce qui était bloquant | Ce qui le remplace |
|---|---|
Le remote est en SSH, ssh est absent de l'image et le port 22 n'est pas tunnelable par le proxy d'allowlist |
url.https://gitlab.com/.insteadOf git@gitlab.com: — la réécriture bascule fetch et push en HTTPS. git pull --ff-only fonctionne donc aussi. |
| Aucune authentification HTTPS dans le conteneur | Un credential.helper qui lit GITLAB_TOKEN dans l'environnement, au moment du push. Le jeton n'est jamais écrit sur disque, ni dans .git/config. |
git config user.email vide — un git commit échouait avant même le push |
user.name / user.email et les GIT_AUTHOR_* / GIT_COMMITTER_*, alimentés par GIT_USER_NAME et GIT_USER_EMAIL de .env. |
La liste exhaustive de ces variables est en référence : Git dans le conteneur (dev local).
La réécriture n'est pas écrite dans le dépôt
Le remote reste en SSH dans .git/config — et il le doit : le common dir est partagé avec l'hôte, où SSH continue de servir. insteadOf agit à l'exécution, seulement dans le conteneur.
Ce que le hook pre-push refuse¶
core.hooksPath pointe sur infra/git-hooks/, qui contient un hook pre-push (infra/git-hooks/pre-push, décision dans infra/git-hooks/pre-push.lib.sh). Il refuse trois familles de références :
| Référence poussée | Verdict | Pourquoi |
|---|---|---|
main, master |
refusé | Branche par défaut. Une MR de lot cible sa branche parente, jamais main. |
*-etape-* (forme <iid>-etape-<n>-<slug>) |
refusé | Branche d'intégration d'une étape. Un push direct court-circuiterait la revue de toute l'étape. |
Tout tag (refs/tags/*) |
refusé | Dans ce projet, taguer déploie en production : build, docker push de l'image, signature, release. Cf. Créer un tag de release. |
La suppression d'une branche protégée (git push origin :main) est refusée elle aussi — c'est la même commande, avec un effet pire.
Un refus affiche la référence en cause, la raison, et la marche à suivre. Il sort en 1 : rien n'est publié.
Deux limites à connaître plutôt qu'à découvrir
- Le hook est versionné. Un worktree resté sur une branche antérieure à sa création ne le porte pas — et git saute un
hooksPathinexistant en silence, sans erreur ni avertissement. Le remède est le même que pourcompose.worktree.yaml: rebaser la branche du worktree (cf. Mon worktree démarre sans alias ni confinement). - Le hook est côté client.
git push --no-verifyle contourne, comme n'importe quel hook git. Il empêche l'accident, pas la malveillance : la vraie barrière est côté serveur, dans les branches protégées GitLab.
Le raisonnement complet sur ce qui a été ouvert et ce qui le borne est dans Pourquoi l'agent pousse lui-même, et ce qui le retient.
Pousser une référence refusée par le hook¶
Le refus vise l'automatisation, pas vous. Quand le geste est délibéré — fusionner une branche d'étape, créer un tag de release —, deux voies :
-
Depuis l'hôte, dans le worktree ou le dépôt principal. Le hook n'y est pas armé (
core.hooksPathne vit que dans l'environnement du conteneur) et votre remote SSH s'applique : -
Pour un tag de release, ne poussez pas de tag du tout : la pipeline
tag:createle crée côté serveur via l'API GitLab. C'est la procédure du projet, indépendamment de ce hook — cf. Créer un tag de release.
Pour Claude Code, git push passe toujours par un script
La règle projet « actions à effet remote = script obligatoire » couvre git push, glab mr create|merge|close et toute requête glab api en écriture. Elle reste la règle alors même que le push est devenu techniquement possible : elle sert à relire le payload (message de commit, corps de MR) avant publication. Source de vérité, y compris l'exception du run multi-lots : .claude/skills/_shared/actions-remote-scripts.md. Les lectures — git status|log|diff|fetch, glab mr list|view, glab ci status — restent libres.
Côté permissions, .claude/settings.json dénie git push au main Claude : le push part du script, pas de l'agent qui tape la commande.
Ce que le conteneur reçoit pour le jeton¶
GITLAB_TOKEN est mis à disposition du conteneur php par deux mécanismes complémentaires (compose.override.yaml) :
| Mécanisme | Effet |
|---|---|
env_file: ${HOME}/.kirexo/secrets/gitlab-token (required: false) |
Publie GITLAB_TOKEN dans l'environnement de tous les process du conteneur, y compris un docker compose exec -T non interactif. C'est cette valeur que lit le credential helper. |
${HOME}/.kirexo/secrets:/run/secrets:ro |
Rend le jeton relisable à chaud en /run/secrets/gitlab-token après une rotation, sans recréer le conteneur. |
C'est le dossier qui est monté, jamais le fichier : un bind de fichier attache un inode, et tout éditeur qui écrit un temporaire puis le renomme laisserait le conteneur sur l'ancienne valeur, orpheline.
GITLAB_TOKEN ne doit jamais passer par environment:
La spécification Compose donne à environment la précédence sur env_file, « même si la valeur est vide ou indéfinie ». Une ligne GITLAB_TOKEN: ${GITLAB_TOKEN:-} viderait donc le jeton en silence. Même règle pour le credential helper, qui ne doit contenir que la lecture de la variable, jamais sa valeur.
Le conteneur pose aussi GLAB_CONFIG_DIR=/home/app/.config/glab-cli. Sans elle, glab est inutilisable : l'image FrankenPHP pose XDG_CONFIG_HOME=/config, dont glab dérive /config/glab-cli/ — un volume nommé root:root où il tente d'écrire un fichier temporaire à chaque lancement. L'échec (failed to read configuration: … permission denied) survient avant toute lecture du jeton.
GITLAB_TOKEN suffit à authentifier glab ; il ne suffit pas à le faire démarrer.
Vérifier¶
# Dans le conteneur
env | grep -c '^GITLAB_TOKEN=' # 1
git config --get user.email # non vide
git ls-remote origin HEAD # affiche le SHA de la HEAD distante
glab auth status # mentionne « environment variable GITLAB_TOKEN »
Si git ls-remote réussit, le transport HTTPS et le jeton sont bons : le push passera.
Contrôle du garde-fou, sur une branche jetable :
Dépannage¶
GITLAB_TOKEN absent — cf. docs/how-to/creer-le-jeton-gitlab-de-kirexo.md— le credential helper échoue franchement plutôt que de tenter une authentification vide. Le conteneur a été créé avant que~/.kirexo/secrets/gitlab-tokenn'existe (Compose ignore silencieusement une entréeenv_fileabsente,required: false). Dépannage dans le shell courant :set -a; . /run/secrets/gitlab-token; set +a. Correctif durable :castor wt:up <ticket>côté hôte, qui recrée le service. Cf. Propager le jeton aux conteneurs.could not read Username for 'https://gitlab.com'— git a tenté un prompt interactif alors queGIT_TERMINAL_PROMPT=0l'interdit : le credential helper n'est pas dans l'environnement. Le conteneur date d'avant son ajout ; recréez-le depuis l'hôte.fatal: Authentication failed/403 Forbiddenau push — le jeton est expiré, révoqué, ou son scope est insuffisant. Le scopeapisuffit àglab; pour legit pushHTTPS, un403a été constaté avecapiseul : ajouterwrite_repository. Cf. Rotation.error: cannot run ssh/Permission denied (publickey)depuis le conteneur — la réécritureinsteadOfn'est pas appliquée : git parle encore SSH, oropenssh-clientn'est pas dans l'image (et il n'a pas vocation à y être — le proxy d'allowlist ne filtre pas le port 22). Vérifiezgit config --get-regexp '^url\.'; si la sortie est vide, le conteneur est antérieur à cette configuration : recréez-le.- Le push sur une branche de lot est refusé — lisez le nom affiché : une branche contenant
-etape-est traitée comme une branche d'intégration. C'est le motif le plus large du hook, et il ne peut pas l'être moins : branche de lot et branche de ticket partagent la forme<iid>-<slug>, seul le segmentetapeles distingue. - Le hook ne s'applique pas du tout —
git config --get core.hooksPathdoit rendre/app/infra/git-hooks, et ce chemin doit exister. UnhooksPathabsent n'est pas une erreur pour git : il saute les hooks sans rien dire. Cas typique : branche antérieure au lot qui a créé le hook. glab: failed to read configuration: open /config/glab-cli/… permission denied—GLAB_CONFIG_DIRmanque dans l'environnement du conteneur. L'échec n'a rien à voir avec le jeton : il survient avant sa lecture. Cf. le dépannage de la page jeton.- Deux versions de
glabqui ne se comportent pas pareil — l'hôte porte une1.36.x, le conteneur une1.112.x. Certaines sous-commandes n'existent que dans l'une, et la 1.36 a déjà échoué sans message sur un appel API. Pour un script, préférezcurl+jq, qui rendent un code HTTP explicite et se comportent identiquement des deux côtés.
Voir aussi¶
- Créer et faire tourner le jeton GitLab de Kirexo — création, portée, vérification, rotation, révocation.
- Pourquoi l'agent pousse lui-même, et ce qui le retient — l'arbitrage de sécurité derrière ce dispositif.
- Git dans le conteneur (dev local) — les variables qui portent cette configuration.
- Créer et détruire un worktree — où vit le worktree côté hôte, et ce que le common dir partagé implique.
- Modèle de menace et contrat de confinement — pourquoi le
.gitpartagé est une limite assumée deC8.