Déployer depuis GitHub (deploy-hub)¶

Avec deploy-hub, un git push sur la bonne branche met à jour la CT toute seule : récupération du code, puis lancement du script de déploiement du projet.

Comment ça marche¶

flowchart LR
  A[git push] --> B[GitHub]
  B -- webhook signé --> C[Nginx CT 104]
  C --> D[deploy-hub CT 105]
  D -- SSH, clé restreinte --> E[agent dans la CT du projet]
  E --> F["git fetch + fast-forward<br/>puis ./deploy.sh"]

Le hub lit la liste des projets dans repos.yml (repo deploy-hub). Un push sur ce repo recharge le hub tout seul.
Le hub ne peut rien faire d'autre dans la CT que lancer l'agent : sa clé SSH est limitée à cette commande, à son adresse, et aux dossiers autorisés.
Un seul déploiement à la fois par repo ; les pushs suivants attendent leur tour.

Brancher un projet¶

1. Préparer la CT¶

Le repo doit être cloné dans la CT et la CT doit pouvoir faire git fetch toute seule. Pour un repo privé, on utilise une deploy key en lecture seule, propre à ce repo :

# dans la CT
ssh-keygen -t ed25519 -N '' -C '<CTID>-<projet>' -f /root/.ssh/id_ed25519
cat /root/.ssh/id_ed25519.pub

Coller la clé dans GitHub : repo du projet → Settings → Deploy keys → Add deploy key, sans cocher Allow write access. Puis :

git clone git@github.com:<owner>/<repo>.git /opt/<projet>

Jamais de clé personnelle dans une CT

Une clé SSH ajoutée à ton compte GitHub donne accès à tous tes repos, en écriture. Si la CT est compromise, tout ton compte l'est. Une deploy key ne donne accès qu'à un repo, en lecture.

2. Installer l'agent¶

Sur l'hôte Proxmox :

deploy-hub-add <CTID> [/chemin/du/repo]

La commande installe l'agent dans la CT, autorise la clé du hub et affiche le bloc à ajouter à repos.yml.

3. Déclarer le projet¶

Coller le bloc dans repos.yml du repo deploy-hub, puis commit et push :

repos:
  <owner>/<repo>:
    host: 10.0.0.<XX>   # CT <CTID>
    path: /opt/<projet>
    branch: main
    # user: root        (par défaut)
    # port: 22          (par défaut)

4. Écrire `deploy.sh` (optionnel)¶

S'il existe à la racine du repo, l'agent le lance après la mise à jour du code, avec ces variables :

Variable	Contenu
`OLD_SHA`	commit avant la mise à jour
`NEW_SHA`	commit déployé
`BRANCH`	branche déployée
`REPO_DIR`	dossier du repo dans la CT

Exemple pour une appli Node lancée par un service systemd :

#!/bin/sh
set -eu
cd "$REPO_DIR"
# réinstaller les dépendances seulement si elles ont changé
if git diff --name-only "$OLD_SHA" "$NEW_SHA" | grep -q '^package-lock.json$'; then
  npm ci
fi
npm run build
systemctl restart <service>

Penser à le rendre exécutable : git update-index --chmod=+x deploy.sh.

5. Tester¶

Pousser un petit commit, puis dans la CT 105 :

deploy-hub list                     # projets connus et dernier état
deploy-hub logs <owner>/<repo>      # journal du dernier déploiement
deploy-hub run <owner>/<repo>       # relancer à la main
journalctl -u deploy-hub -f         # suivre le hub en direct

Quand l'agent refuse de déployer¶

L'agent préfère ne rien faire plutôt qu'écraser quelque chose :

Fichiers modifiés directement dans la CT: Il refuse tant que des fichiers suivis par git sont modifiés localement. Les commiter et pousser depuis la CT, ou les annuler (git checkout -- <fichier>). Les fichiers propres à la machine (.env, données) doivent être dans .gitignore.
Historique réécrit (force-push): Il ne fait que des fast-forward. Après un force-push, il faut réaligner la CT à la main (git reset --hard origin/<branche>, après avoir vérifié ce qu'on perd).

Limites actuelles¶

Seuls les repos du compte qui a installé l'application GitHub de deploy-hub déclenchent un déploiement. Le branchement des repos de l'organisation est prévu.