Aller au contenu

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.com avec au moins le rôle Developer sur shaurifr/kirexo (ou les droits d'inviter un membre, pour l'option « compte bot »).
  • Le fichier ~/.kirexo/secrets/gitlab-token existe déjà, en gabarit : il est créé par castor claude:space, joué automatiquement au début de castor docker:up. S'il manque, le créer depuis un terminal hôte :

    castor claude:space
    

    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)

  1. Créer un compte GitLab dédié (par exemple kirexo-bot), avec une adresse e-mail que vous contrôlez.
  2. Depuis shaurifr/kirexo : Manage → Members → Invite members, inviter kirexo-bot avec le rôle Developer. Ne l'inviter sur aucun autre projet — c'est toute la valeur de l'option.
  3. Se connecter avec le compte bot, puis User Settings → Access Tokens → Add new token :

    Champ Valeur
    Token name kirexo-dev
    Expiration date une date dans 30 à 90 jours (GitLab impose une expiration)
    Scopes api
  4. 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 :

set -a; . /run/secrets/gitlab-token; set +a

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

. ~/.kirexo/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.

  1. Créer un nouveau jeton sur GitLab (étape 2a ou 2b).
  2. Remplacer la valeur dans ~/.kirexo/secrets/gitlab-token, avec l'éditeur de votre choix.
  3. 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.
  4. Révoquer l'ancien jeton sur GitLab : User Settings → Access Tokens → Revoke.
  5. 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-token affiche 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) :

  1. Révoquer d'abord sur GitLab : User Settings → Access Tokens → Revoke. Avant tout diagnostic.
  2. Créer un jeton de remplacement et rejouer la rotation ci-dessus.
  3. 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 push HTTPS 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.yaml injecte par l'environnement la réécriture url.https://gitlab.com/.insteadOf git@gitlab.com: et un credential.helper qui lit GITLAB_TOKEN dans 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.email de 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 glab personnelle reste intacte. glab lit les jetons dans cet ordre : variable d'environnement GITLAB_TOKEN, puis le config.yml de 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:space dit « jeton GitLab non renseigné (gabarit) » alors que vous l'avez renseigné : la ligne est probablement commentée (#GITLAB_TOKEN=…) ou préfixée par export. Cf. l'encart de l'étape 3.
  • castor claude:space dit « jeton GitLab vide » : la ligne GITLAB_TOKEN= est bien là, mais sans valeur.
  • env | grep -c '^GITLAB_TOKEN=' renvoie 0 dans le conteneur : le conteneur a été créé avant que le fichier n'existe (Compose ignore silencieusement une entrée env_file absente, par required: false). Charger la valeur tout de suite avec set -a; . /run/secrets/gitlab-token; set +a, puis recréer le conteneur depuis l'hôte — cf. étape 4.
  • glab s'arrête sur failed to read configuration: open /config/glab-cli/… permission denied : la variable GLAB_CONFIG_DIR manque dans l'environnement du conteneur. L'image FrankenPHP/Caddy pose XDG_CONFIG_HOME=/config, un volume appartenant à root dont glab dérive son répertoire de configuration ; l'utilisateur app ne peut pas y écrire le fichier temporaire créé à chaque lancement. L'échec survient avant toute lecture de GITLAB_TOKEN — le jeton n'y est pour rien. Le service php de compose.override.yaml définit GLAB_CONFIG_DIR: /home/app/.config/glab-cli : si env | grep GLAB_CONFIG_DIR ne rend rien, le conteneur date d'avant cet ajout, il faut le recréer.
  • glab api user renvoie 401 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érifier glab api user | jq -r '.username'.
  • ls -la /run/secrets/gitlab-token affiche un compteur de liens à 0 et 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