02 - Installer GitLab Runner sur ton VPS

Ce que tu vas apprendre

Installer GitLab Runner sur Ubuntu 25.04 (sans le dépôt apt)
Enregistrer le runner avec ton projet GitLab
Configurer le shell executor
Regler les permissions Docker et Git

Prerequisites

01 - L'architecture : comprendre le setup
Un VPS Ubuntu avec Docker installe
Un projet sur GitLab

Le dépôt apt ne marche pas sur Ubuntu 25.04

Premier piège. La documentation GitLab te dit d'ajouter le dépôt apt officiel et de faire apt install gitlab-runner. Sauf que le dépôt ne supporte pas Ubuntu 25.04 (nom de code "plucky"). Tu vas avoir une erreur de repo introuvable, et tu vas perdre 20 minutes a chercher pourquoi.

La solution : telecharger le binaire directement depuis les serveurs de GitLab. C'est ce qui est recommande dans la doc pour les distributions non supportees.

bashsudo curl -L --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64"

sudo chmod +x /usr/local/bin/gitlab-runner

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner

sudo gitlab-runner start

Cinq commandes. Le binaire est telecharge, l'utilisateur système est créé, le service est installe et démarré. Tu peux vérifier que ca tourne avec sudo gitlab-runner status.

Enregistrer le runner

Va dans ton projet GitLab, puis Settings > CI/CD > Runners. Clique sur "New project runner". Choisis Linux, donne-lui un tag (par exemple paltemps), et récupéré le token d'enregistrement.

bashsudo gitlab-runner register \
  --url https://gitlab.com \
  --token glrt-XXXXXXXXXXXXXXXXXXXX

Le CLI te pose quelques questions. Pour l'executor, choisis shell :

Enter an executor: shell

Pourquoi shell et pas Docker ? Le Docker executor lance chaque job dans un conteneur frais. C'est bien pour de l'intégration continue classique (build, tests), mais pour du déploiement, c'est absurde. Tu veux que le job exécuté docker compose up sur le VPS lui-meme, pas dans un conteneur isole qui n'a pas acces a ton Docker host. Le shell executor exécuté les commandes directement sur la machine, avec l'utilisateur gitlab-runner. C'est exactement ce qu'il nous faut.

Ajouter gitlab-runner au groupe docker

Par défaut, l'utilisateur gitlab-runner n'a pas le droit d'utiliser Docker. Tu vas avoir un "Permission denied" sur docker compose build. La fix :

bashsudo usermod -aG docker gitlab-runner

Redemarre le runner pour que le changement de groupe prenne effet :

bashsudo gitlab-runner restart

Tu peux vérifier avec :

bashsudo -u gitlab-runner docker ps

Si ca affiche la liste des conteneurs (meme vide), c'est bon.

Configurer l'acces Git

Le runner doit pouvoir faire git pull sur ton repo. Pour ca, il lui faut une clé SSH. Genere-la pour l'utilisateur gitlab-runner :

bashsudo -u gitlab-runner ssh-keygen -t ed25519 -C "gitlab-runner@vps" -f /home/gitlab-runner/.ssh/id_ed25519 -N ""

Affiche la clé publique :

bashsudo cat /home/gitlab-runner/.ssh/id_ed25519.pub

Va dans ton projet GitLab, Settings > Repository > Deploy keys, et ajoute cette clé publique. Coche "Grant write access" seulement si tu en as besoin (pour notre cas, la lecture suffit).

Il faut aussi ajouter gitlab.com aux known hosts, sinon le premier git pull va bloquer sur "Host key vérification failed" :

bashsudo -u gitlab-runner bash -c 'ssh-keyscan gitlab.com >> ~/.ssh/known_hosts'

Et tant qu'on y est, configure le safe.directory pour éviter l'erreur "dubious ownership" (on en reparle dans l'article troubleshooting) :

bashsudo -u gitlab-runner git config --global safe.directory '*'

Le profil bash du runner

Un truc qui m'a fait perdre du temps. Par défaut, l'utilisateur gitlab-runner n'a pas de .bash_logout ni de .bashrc correctement configures. Certaines versions de GitLab Runner essaient de sourcer ces fichiers au démarrage du job. Si ils n'existent pas ou sont mal formes, tu obtiens un cryptique "prepare environment: exit status 1".

La solution preventive :

bashsudo -u gitlab-runner bash -c 'touch ~/.bash_logout'
sudo -u gitlab-runner bash -c 'cp /etc/skel/.bashrc ~/. 2>/dev/null || touch ~/.bashrc'

C'est le genre de truc qui n'est documente nulle part et qui te fait perdre une heure sur Stack Overflow.

Tester que tout marche

Avant d'écrire le .gitlab-ci.yml, vérifié manuellement que le runner peut faire ce qu'on attend de lui :

bashsudo -u gitlab-runner bash -c 'cd /chemin/vers/ton/projet && git pull'
sudo -u gitlab-runner bash -c 'cd /chemin/vers/ton/projet && docker compose build'
sudo -u gitlab-runner bash -c 'cd /chemin/vers/ton/projet && docker compose up -d'

Si ces trois commandes passent, le runner est pret. Si l'une d'elles echoue, c'est un problème de permissions ou de config, et c'est mieux de le regler maintenant plutot que de debugger un pipeline à distance.

Tu peux aussi vérifier dans l'interface GitLab que le runner apparaît bien avec un point vert dans Settings > CI/CD > Runners. Si il est gris, le service n'est peut-etre pas lance (sudo gitlab-runner start).

Recapitulatif

A ce stade, tu as :

GitLab Runner installe en binaire (pas via apt)
Le runner enregistre avec ton projet en shell executor
L'utilisateur gitlab-runner dans le groupe docker
Une clé SSH deploy pour git pull
Les fichiers de profil bash en place

Dans le prochain article, on écrit le .gitlab-ci.yml qui va lier tout ca ensemble.

Navigation : Precedent : 01 - L'architecture | Suivant : 03 - Écrire le .gitlab-ci.yml

Sources

Install GitLab Runner manually par GitLab
Registering a runner par GitLab
GitLab Deploy Keys par GitLab Docs

Retrouve d'autres articles techniques sur paltemps.fr.