Créer et faire tourner le jeton GitLab de Kirexo¶
Vous êtes développeur·se sur Kirexo et vous voulez que glab et les git push HTTPS fonctionnent — depuis l'hôte comme depuis le conteneur — avec un jeton qui n'ouvre que ce projet, et pas les 20+ projets de votre compte GitLab.
Cette recette couvre le choix du type de jeton, sa création, son écriture dans ~/.kirexo/secrets/gitlab-token, sa propagation aux conteneurs, sa vérification, sa rotation et sa révocation.
Prérequis¶
- Un compte sur
gitlab.comavec au moins le rôle Developer surshaurifr/kirexo(ou les droits d'inviter un membre, pour l'option « compte bot »). -
Le fichier
~/.kirexo/secrets/gitlab-tokenexiste déjà, en gabarit : il est créé parcastor claude:space, joué automatiquement au début decastor docker:up. S'il manque, le créer depuis un terminal hôte :Cf.
castor claude:space. La cible est hôte-only et idempotente : la relancer ne casse rien.
Où vit la règle, où vit la procédure
L'emplacement du fichier, ses permissions et l'interdiction absolue de le versionner sont fixés par la fiche de règles projet .claude/skills/_shared/secrets-env.md (source de vérité unique des secrets). Cette page-ci décrit les gestes, pas la règle.
Le jeton a déménagé — ~/.kirexo/secrets/gitlab-token
Il vivait auparavant en ~/.kirexo/gitlab-token. C'est désormais le dossier ~/.kirexo/secrets (mode 700) qui est monté sur /run/secrets dans le conteneur ; le motif est expliqué dans Ce qui se propage à chaud, et ce qui ne se propage pas. Côté conteneur, rien ne change : le jeton reste lisible en /run/secrets/gitlab-token.
Si vous portez encore un jeton à l'ancien emplacement, castor claude:space le déplace au premier passage (mode 600 conservé) et le rapporte en ACTION. Rien à faire à la main. Si les deux fichiers existent, la cible n'écrase rien et vous demande de trancher — cf. castor claude:space.
Une contrainte accompagne ce déménagement : ne déposer que le jeton dans ce dossier, pour la raison exposée à la même section.
Étape 1 — Choisir le type de jeton¶
Le mécanisme est indépendant du type de jeton : le fichier, le montage en lecture seule, l'injection par env_file et la précédence de GITLAB_TOKEN sont identiques dans les trois cas. Seule change la portée obtenue.
| Option | Portée obtenue | Statut |
|---|---|---|
Project access token sur shaurifr/kirexo |
Kirexo seul | ❌ Exclu — les project access tokens (et group access tokens) exigent Premium/Ultimate sur gitlab.com. Kirexo est en tier gratuit. |
Compte bot dédié (kirexo-bot), invité Developer sur shaurifr/kirexo uniquement, avec un PAT de scope api |
Kirexo seul | ✅ Retenu — gratuit. Coût : un siège sur les 5 du groupe Free. |
| PAT personnel distinct de celui utilisé sur l'hôte, expiration courte (30 à 90 jours) | Inchangée (tous vos projets) | ✅ Repli — à privilégier si le siège du groupe Free est un blocage. |
Le compte bot apporte un effet de bord utile : les merge requests et issues créées via l'API apparaissent au nom du bot, et non au vôtre — la traçabilité agent / humain devient lisible directement dans l'historique GitLab.
Le PAT personnel distinct conserve, lui, un intérêt propre : sa révocation est isolée. Le révoquer ne casse ni votre glab personnel ni vos autres projets, alors que révoquer le jeton de compte les casserait tous.
Étape 2a — Créer le compte bot (option retenue)¶
- Créer un compte GitLab dédié (par exemple
kirexo-bot), avec une adresse e-mail que vous contrôlez. - Depuis
shaurifr/kirexo: Manage → Members → Invite members, inviterkirexo-botavec le rôle Developer. Ne l'inviter sur aucun autre projet — c'est toute la valeur de l'option. -
Se connecter avec le compte bot, puis User Settings → Access Tokens → Add new token :
Champ Valeur Token name kirexo-devExpiration date une date dans 30 à 90 jours (GitLab impose une expiration) Scopes api -
Create personal access token, puis copier la valeur immédiatement — GitLab ne la ré-affiche jamais.
Scope api — et le cas du git push
api couvre les appels d'API dont glab a besoin (issues, merge requests, notes). Un scope read_api ne suffirait pas.
Pour le git push en HTTPS, la prudence s'impose : la pipeline de ce projet a constaté empiriquement un 403 Forbidden au moment du push avec un jeton de scope api seul (cf. Bootstrapper la pipeline CI). Si vos push retombent en 403, régénérez le jeton en ajoutant write_repository — c'est le seul élargissement de scope justifié ici.
Ce cas n'est plus marginal : ce même jeton authentifie désormais les git push lancés depuis le conteneur (cf. Pousser sur GitLab depuis un worktree). Sans write_repository, glab fonctionnera et le push échouera.
Étape 2b — Créer le PAT personnel de repli¶
Si vous partez sur le repli, la création est identique, sur votre compte : User Settings → Access Tokens, nom kirexo-dev, expiration 30 à 90 jours, scope api.
Un point n'est pas optionnel : ce jeton doit être distinct de celui que vous utilisez déjà côté hôte pour vos autres projets. Sinon la révocation cesse d'être isolée et vous perdez le seul bénéfice de l'option.
Étape 3 — Écrire le jeton dans ~/.kirexo/secrets/gitlab-token¶
Ouvrir le fichier avec votre éditeur et décommenter la ligne du gabarit en y collant la valeur :
# Jeton GitLab dédié à Kirexo — NE JAMAIS COMMITER, NE JAMAIS SORTIR DE CE FICHIER.
GITLAB_TOKEN=glpat-VotreValeurIci
N'importe quel éditeur convient : vim, VS Code, sed -i — le montage porte sur le dossier, pas sur le fichier, donc la valeur reste visible dans le conteneur même après un remplacement du fichier.
Puis vérifier les permissions :
chmod 600 ~/.kirexo/secrets/gitlab-token
stat -c '%a %n' ~/.kirexo/secrets ~/.kirexo/secrets/gitlab-token # attendu : 700 … et 600 …
Format dotenv strict — pas de export
La ligne s'écrit GITLAB_TOKEN=glpat-…, sans préfixe export, sans espace autour du =.
Le fichier a trois consommateurs, qui attendent tous du dotenv : env_file: de Docker Compose (bloc services.php de compose.override.yaml), ~/.kirexo/env.sh côté hôte, et le montage /run/secrets/gitlab-token relu à la volée dans le conteneur. Les deux derniers le sourcent entre un set -a et un set +a — ils n'ont donc pas besoin de l'export.
Surtout, la sonde d'état du bootstrap (cs_token_state, dans infra/claude-space/bootstrap.lib.sh) ne reconnaît que les lignes commençant par GITLAB_TOKEN=. Avec export GITLAB_TOKEN=…, castor claude:space continuera d'annoncer « jeton GitLab non renseigné (gabarit) » alors que le jeton est bien là. Faux négatif garanti, et une bonne demi-heure perdue à chercher au mauvais endroit.
Étape 4 — Propager le jeton aux conteneurs¶
Le jeton a deux chemins d'arrivée dans le conteneur, et ils ne se propagent pas de la même façon.
Tout de suite, dans un shell déjà ouvert — le montage /run/secrets/gitlab-token reflète immédiatement ce que vous venez d'écrire :
La variable est alors présente pour ce shell et les process qu'il lance. C'est suffisant pour enchaîner sur l'étape 5.
Durablement — la variable GITLAB_TOKEN de l'environnement du conteneur, elle, vient de env_file:, lu à la création du conteneur. Pour qu'elle soit là pour tous les process (y compris ceux lancés par l'IDE), il faut recréer le conteneur, depuis un terminal hôte :
# HÔTE — dans le worktree concerné
castor wt:up <ticket>
# HÔTE — ou, sur le dépôt principal
castor docker:up
Le service php monte le dépôt (- .:/app, compose.override.yaml) : le conteneur recréé repart donc sur le code courant, pas sur celui figé dans l'image. Un simple restart ne suffit pas — le conteneur n'est pas recréé, env_file: n'est pas relu.
Recréer le conteneur coupe la session Claude Code en cours
Le process claude vit dans le conteneur php. Terminez ou sauvegardez votre session avant de jouer la commande ; l'espace utilisateur (CLAUDE_CONFIG_DIR) étant hors du conteneur, la conversation reste reprenable par claude --resume (cf. Pourquoi l'espace Claude est commun à tous les worktrees).
Côté hôte, sourcer env.sh
Ce fichier est régénéré à chaque passage du bootstrap. Il exporte CLAUDE_CONFIG_DIR et charge le jeton dans l'environnement du shell courant. À sourcer dans chaque terminal hôte où vous travaillez sur Kirexo (ou depuis votre ~/.bashrc / ~/.zshrc, à votre convenance).
Étape 5 — Vérifier¶
Depuis le conteneur (castor docker:sh) ou depuis un terminal hôte où env.sh a été sourcé :
env | grep -c '^GITLAB_TOKEN=' # 1
glab auth status # jeton issu de l'environnement
glab api user | jq -r '.username' # kirexo-bot (ou votre login)
glab api 'projects?membership=true&per_page=100' | jq 'length' # 1 avec le compte bot
La dernière ligne est celle qui compte : c'est la mesure de la portée réellement obtenue. 1 avec le compte bot, votre nombre de projets avec le PAT personnel de repli.
Le credential helper git, lui, se vérifie ainsi :
printf 'protocol=https\nhost=gitlab.com\n\n' | glab auth git-credential get | grep -c '^password=' # 1
git ls-remote origin HEAD # SHA de la HEAD distante
Rotation¶
À faire à chaque expiration, et à intervalle raisonnable même sans expiration.
- Créer un nouveau jeton sur GitLab (étape 2a ou 2b).
- Remplacer la valeur dans
~/.kirexo/secrets/gitlab-token, avec l'éditeur de votre choix. - Propager, comme à l'étape 4 : relecture à chaud dans les shells ouverts (
set -a; . /run/secrets/gitlab-token; set +a), puis recréation du conteneur depuis l'hôte pour que la nouvelle valeur soit dans son environnement. - Révoquer l'ancien jeton sur GitLab : User Settings → Access Tokens → Revoke.
- Rejouer les vérifications de l'étape 5.
Ce qui se propage à chaud, et ce qui ne se propage pas¶
Le dossier ~/.kirexo/secrets est monté en lecture seule sur /run/secrets dans le conteneur. Le jeton y est donc lisible en /run/secrets/gitlab-token, et ce chemin reflète la nouvelle valeur immédiatement, sans redémarrage : un process déjà lancé peut la relire à la volée (set -a; . /run/secrets/gitlab-token; set +a).
C'est bien le dossier qui est monté, et non le fichier. La distinction n'est pas cosmétique :
- un bind de fichier attache un inode, pas un chemin. Tout éditeur qui écrit un temporaire puis le renomme par-dessus la cible — vim, VS Code,
sed -i, la quasi-totalité d'entre eux — crée un nouvel inode côté hôte. Le conteneur reste attaché à l'ancien, désormais orphelin, et ne voit jamais la nouvelle valeur. Sa signature :ls -la /run/secrets/gitlab-tokenaffiche un compteur de liens à0; - un bind de dossier résout les entrées à chaque accès. Le remplacement d'inode qui se produit dans le dossier est vu tout de suite.
Le montage a donc déménagé du fichier vers le dossier pour que la promesse de rotation à chaud soit effectivement tenue — elle ne l'était pas tant que le fichier était bindé directement, alors même que cette page prescrivait d'éditer le jeton avec un éditeur.
La variable GITLAB_TOKEN de l'environnement du conteneur, elle, reste figée à la création : env_file: n'est lu qu'à ce moment-là. Le montage sert de source de vérité relisable, pas de substitut à la recréation.
Le dossier ~/.kirexo/secrets ne contient que le jeton
Un dossier monté expose tout son contenu. Un fichier ajouté à côté du jeton devient lisible dans le conteneur sans créer de point de montage supplémentaire, donc sans que l'invariant de confinement C1 — qui ne raisonne que sur les destinations de montage — puisse le détecter. Aucun autre secret, aucune sauvegarde, aucun brouillon dans ce dossier.
Révocation et fuite¶
Si le jeton fuit (collé dans une issue, commité par accident, apparu dans un log) :
- Révoquer d'abord sur GitLab : User Settings → Access Tokens → Revoke. Avant tout diagnostic.
- Créer un jeton de remplacement et rejouer la rotation ci-dessus.
- Chercher ensuite la cause.
C'est exactement ce que le jeton dédié rend supportable : révoquer un jeton qui n'ouvre qu'un seul projet ne casse ni votre glab personnel, ni vos autres dépôts, ni les jetons de vos collègues. Révoquer un jeton de compte, si.
Ce que le jeton change — et ce qu'il ne change pas¶
- Les
git pushHTTPS passent par ce jeton, hôte comme conteneur — mais pas par le même chemin. Sur l'hôte, c'est la configuration git de votre poste qui le consomme. Dans le conteneur,compose.override.yamlinjecte par l'environnement la réécritureurl.https://gitlab.com/.insteadOf git@gitlab.com:et uncredential.helperqui litGITLAB_TOKENdans l'environnement au moment du push : rien n'est écrit dans.git/config, et le jeton ne touche jamais le disque. Si la variable manque, le helper échoue franchement et renvoie vers cette page. Détail des variables : Git dans le conteneur (dev local) ; le geste : Pousser sur GitLab depuis un worktree. - L'auteur des commits reste inchangé. Il vient de
user.name/user.emailde git, pas du jeton. Le jeton n'agit que sur l'authentification du transport et sur les objets créés via l'API — merge requests, issues, notes — qui apparaîtront au nom du bot si vous avez retenu cette option. - Votre configuration
glabpersonnelle reste intacte.glablit les jetons dans cet ordre : variable d'environnementGITLAB_TOKEN, puis leconfig.ymlde son répertoire de configuration. Renseigner la variable ne réécrit rien dans votre configuration : elle prend simplement le dessus, le temps du process. Dans le conteneur, ce répertoire est de toute façon un répertoire à lui,/home/app/.config/glab-cli(GLAB_CONFIG_DIR), sans aucun lien avec celui de l'hôte — qui n'est plus monté.
Dépannage¶
castor claude:spacedit « jeton GitLab non renseigné (gabarit) » alors que vous l'avez renseigné : la ligne est probablement commentée (#GITLAB_TOKEN=…) ou préfixée parexport. Cf. l'encart de l'étape 3.castor claude:spacedit « jeton GitLab vide » : la ligneGITLAB_TOKEN=est bien là, mais sans valeur.env | grep -c '^GITLAB_TOKEN='renvoie0dans le conteneur : le conteneur a été créé avant que le fichier n'existe (Compose ignore silencieusement une entréeenv_fileabsente, parrequired: false). Charger la valeur tout de suite avecset -a; . /run/secrets/gitlab-token; set +a, puis recréer le conteneur depuis l'hôte — cf. étape 4.glabs'arrête surfailed to read configuration: open /config/glab-cli/… permission denied: la variableGLAB_CONFIG_DIRmanque dans l'environnement du conteneur. L'image FrankenPHP/Caddy poseXDG_CONFIG_HOME=/config, un volume appartenant àrootdontglabdérive son répertoire de configuration ; l'utilisateurappne peut pas y écrire le fichier temporaire créé à chaque lancement. L'échec survient avant toute lecture deGITLAB_TOKEN— le jeton n'y est pour rien. Le servicephpdecompose.override.yamldéfinitGLAB_CONFIG_DIR: /home/app/.config/glab-cli: sienv | grep GLAB_CONFIG_DIRne rend rien, le conteneur date d'avant cet ajout, il faut le recréer.glab api userrenvoie401 Unauthorized: jeton expiré, révoqué, ou valeur tronquée à la copie. Régénérer et rejouer la rotation.glab api 'projects?membership=true'renvoie bien plus d'un projet avec un compte bot : le bot a été invité ailleurs, ou vous avez collé le jeton d'un autre compte. Vérifierglab api user | jq -r '.username'.ls -la /run/secrets/gitlab-tokenaffiche un compteur de liens à0et le contenu est resté à l'ancienne valeur : le conteneur date d'avant le passage au bind de dossier, et reste attaché à un inode orphelin. Le recréer depuis l'hôte — cf. étape 4.
Voir aussi¶
- Pousser sur GitLab depuis un worktree — l'usage courant, une fois le jeton en place.
- Git dans le conteneur (dev local) — le credential helper qui consomme ce jeton, et le hook
pre-pushqu'il arme. castor claude:space— la cible qui prépare~/.kirexo/.- Variables d'environnement — Espace Claude et jeton GitLab (dev local) — la fiche de
GITLAB_TOKENcôté dev, et sa distinction d'avec la variable CI/CD homonyme. - Pourquoi l'espace Claude est commun à tous les worktrees — l'autre moitié de
~/.kirexo/.