Installer un GitLab Runner privé en conteneur LXC sur Proxmox¶

Guide d'installation manuelle, étape par étape, d'un GitLab Runner en conteneur LXC Proxmox, avec l'executor shell : les jobs CI/CD s'exécutent directement dans le conteneur, qui peut ensuite se connecter en SSH vers d'autres conteneurs du réseau pour déclencher des déploiements.

Prérequis¶

Un hôte Proxmox VE avec accès pct
Un token runner GitLab (glrt-...), obtenu depuis GitLab → projet ou groupe → Settings → CI/CD → Runners → Create project/group runner

Valeurs d'exemple utilisées dans ce guide :

Paramètre	Valeur d'exemple
ID du conteneur	`206`
IP fixe	`192.168.1.206/24`
URL GitLab	`https://gitlab.com`
Nom du runner	`pve-shell-runner`
Executor	`shell`

1⃣ Création du conteneur LXC¶

pveam update
pveam available | grep debian-12-standard
pveam download local debian-12-standard_12.7-1_amd64.tar.zst

pct create 206 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
    --hostname gitlab-runner.votre-domaine.tld \
    --memory 1024 \
    --swap 512 \
    --cores 2 \
    --rootfs local-lvm:16 \
    --net0 name=eth0,bridge=vmbr0,ip=192.168.1.206/24,gw=192.168.1.1 \
    --unprivileged 1 \
    --onboot 1

pct start 206

2⃣ Installation des paquets et de GitLab Runner¶

pct exec 206 -- apt-get update
pct exec 206 -- apt-get install -y --no-install-recommends curl git openssh-client ca-certificates

pct exec 206 -- bash -c "
    curl -sL https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | bash
"
pct exec 206 -- apt-get install -y gitlab-runner

3⃣ Clé SSH pour déclencher des déploiements à distance¶

pct exec 206 -- bash -c "
    mkdir -p /home/gitlab-runner/.ssh &&
    chmod 700 /home/gitlab-runner/.ssh &&
    ssh-keygen -t ed25519 -f /home/gitlab-runner/.ssh/id_ed25519 -N '' -q &&
    chown -R gitlab-runner:gitlab-runner /home/gitlab-runner/.ssh
"
pct exec 206 -- cat /home/gitlab-runner/.ssh/id_ed25519.pub

Conserver cette clé publique : elle devra être ajoutée dans ~/.ssh/authorized_keys de chaque conteneur cible que ce runner doit pouvoir déployer.

# Sur un conteneur cible (exemple)
pct exec <CT_ID_CIBLE> -- bash -c "echo '<clé publique du runner>' >> /root/.ssh/authorized_keys"

4⃣ Enregistrement du runner auprès de GitLab¶

pct exec 206 -- gitlab-runner register \
    --non-interactive \
    --url "https://gitlab.com" \
    --token "<RUNNER_TOKEN>" \
    --name "pve-shell-runner" \
    --executor "shell"

pct exec 206 -- systemctl enable --now gitlab-runner

Vérifier que le runner est bien actif :

pct exec 206 -- systemctl is-active gitlab-runner

5⃣ Utilisation dans un pipeline¶

Exemple de job .gitlab-ci.yml qui déclenche un script de déploiement sur un conteneur cible via SSH :

deploy:
  stage: deploy
  script:
    - ssh -o StrictHostKeyChecking=no root@<CT_IP_CIBLE> "/usr/local/bin/mon-service-deploy.sh"
  only:
    - main

Ce modèle garde la logique de déploiement (build, restart de service, etc.) sur le conteneur cible lui-même ; le runner ne fait que déclencher l'exécution via SSH.

⚙️ Points d'administration importants¶

Le RUNNER_TOKEN donne le droit d'exécuter du code arbitraire sur le réseau interne via ce runner — à traiter comme un secret de premier niveau, à ne jamais commiter dans un dépôt.
L'executor shell n'isole pas les jobs entre eux ni du système hôte du conteneur : à réserver à des pipelines de confiance (votre propre code), jamais à des forks ou merge requests externes non vérifiées.
Limiter les clés SSH autorisées sur les conteneurs cibles aux commandes strictement nécessaires (option command= dans authorized_keys) si le runner ne doit déclencher qu'un script précis, plutôt qu'un accès shell complet.
Logs : pct exec 206 -- journalctl -u gitlab-runner -f.
Plusieurs jobs en parallèle : par défaut le runner traite un job à la fois ; ajuster concurrent en tête de /etc/gitlab-runner/config.toml (ex : concurrent = 3) si plusieurs pipelines doivent pouvoir tourner en même temps sur ce conteneur, puis systemctl restart gitlab-runner.
Désenregistrer un runner proprement avant de détruire le conteneur : pct exec 206 -- gitlab-runner unregister --all-runners, sinon le runner reste visible (mais inactif) côté GitLab.

Conclusion¶

Un runner GitLab privé dans le réseau interne permet d'automatiser les déploiements de tous les autres services (wiki, applications internes, etc.) sur simple git push, sans dépendre d'un runner SaaS partagé ni exposer le réseau interne à l'extérieur.