Intégrer GARM avec Gitea Actions : runners LXD à la demande

GARM est installé et son service tourne. Cette étape connecte GARM à votre instance Gitea : vous allez créer un PAT (Personal Access Token), déclarer un endpoint Gitea dans GARM, configurer un pool LXD, et déclencher votre premier job Actions sur un runner éphémère.

Prérequis : GARM v0.2.0 installé et l'API accessible. Voir Installer GARM.

garm-cli v0.2.0 : authentification par profil

Dans GARM v0.2.0, garm-cli n'utilise plus de flags globaux --url, --username, --password. Il fonctionne par profils stockés dans ~/.local/share/garm-cli/config.toml. Le profil actif est celui créé lors de garm-cli init. Pour vous reconnecter : garm-cli profile login -u garmadmin -p "MotDePasse".

Étape 1, Mettre à jour les URLs du contrôleur

Après l'installation, les URLs du contrôleur pointent vers localhost. Gitea (et vos runners) doivent pouvoir les joindre. Mettez à jour avec l'IP réelle de la VM.

garm-cli controller update \
  --metadata-url "http://192.168.122.52:9997/api/v1/metadata" \
  --callback-url "http://192.168.122.52:9997/api/v1/callbacks" \
  --webhook-url  "http://192.168.122.52:9997/webhooks" \
  --agent-url    "http://192.168.122.52:9997/agent"

# Vérifier
garm-cli controller show

URLs contrôleur en production

En production, ces URLs doivent être joignables :

• par Gitea (pour les webhooks) : webhook-url
• par les runners (pour s'enregistrer) : metadata-url, callback-url, agent-url

Si GARM est derrière un reverse proxy (Traefik, Nginx), utilisez les URLs publiques HTTPS.

Étape 2, Créer un PAT Gitea pour GARM

GARM a besoin d'un token Gitea pour interroger les repos, gérer les runners et répondre aux webhooks. Créez un PAT (Personal Access Token) via l'API Gitea.

# Créer le PAT via l'API Gitea
# (adapter l'utilisateur et le mot de passe à votre installation)
curl -X POST \
  -u 'giteaadmin:Admin1234!' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "garm-token",
    "scopes": ["write:repository", "write:organization", "read:user"]
  }' \
  'http://localhost:3000/api/v1/users/giteaadmin/tokens'

La réponse contient le token (champ sha1), notez-le, il ne sera affiché qu'une fois :

{
  "id": 1,
  "name": "garm-token",
  "sha1": "d86697b5ee780c927a4c25dcee8dd327760a111c",
  ...
}

Scopes requis

Les scopes write:repository et write:organization permettent à GARM de gérer les runners enregistrés sur les repos/orgs. Sans ces scopes, GARM pourra créer des containers mais ne pourra pas les enregistrer comme runners dans Gitea.

Étape 3, Déclarer l'endpoint Gitea dans GARM

Un endpoint dans GARM représente une instance Gitea (ou GitHub). Il contient l'URL de base et l'URL de l'API.

garm-cli gitea endpoint create \
  --name        "local-gitea" \
  --description "Gitea local lab" \
  --base-url    "http://192.168.122.52:3000" \
  --api-base-url "http://192.168.122.52:3000"

# Vérifier
garm-cli gitea endpoint list

base-url vs api-base-url

Pour une installation Gitea standard, --base-url et --api-base-url sont identiques. Si Gitea est accessible via un chemin personnalisé (ex. https://exemple.com/gitea), api-base-url serait https://exemple.com/gitea car l'API Gitea est à /api/v1/ relativement à ce chemin.

Étape 4, Ajouter les credentials

Les credentials associent un endpoint à un token d'authentification. Utilisez le PAT créé à l'étape 2.

garm-cli gitea credentials add \
  --endpoint      "local-gitea" \
  --auth-type     "pat" \
  --pat-oauth-token "d86697b5ee780c927a4c25dcee8dd327760a111c" \
  --name          "gitea-creds" \
  --description   "PAT garm-token"

# Vérifier
garm-cli gitea credentials list

Étape 5, Créer un repo de test dans Gitea

Pour tester GARM, vous avez besoin d'un repo Gitea avec Gitea Actions activé.

# Créer le repo
curl -X POST \
  -u 'giteaadmin:Admin1234!' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "garm-test",
    "description": "Repo de test pour GARM runners",
    "private": false,
    "auto_init": true,
    "default_branch": "main"
  }' \
  'http://localhost:3000/api/v1/user/repos'

Étape 6, Ajouter le repo dans GARM

garm-cli repository add \
  --credentials    "gitea-creds" \
  --owner          "giteaadmin" \
  --name           "garm-test" \
  --webhook-secret "garm-webhook-secret-lab2026"

Attendez quelques secondes que le pool manager démarre, puis vérifiez :

garm-cli repository list
# → POOL MGR RUNNING doit être "true"

Pool manager : que se passe-t-il ?

Quand vous ajoutez un repo, GARM démarre un pool manager en arrière-plan. Ce composant surveille les webhooks entrants pour ce repo et décide quand créer ou détruire des runners. Si POOL MGR RUNNING est false après 10 secondes, vérifiez les logs : journalctl -u garm -n 20.

Étape 7, Créer le pool LXD

Un pool définit comment les runners seront créés. Il associe un repo, un provider LXD, une image Ubuntu et des limites (max de runners simultanés).

# Récupérer l'ID du repo
REPO_ID=$(garm-cli repository list --format json | \
  python3 -c "import sys,json; repos=json.load(sys.stdin); \
  print([r['id'] for r in repos if r['name']=='garm-test'][0])")

echo "Repo ID: ${REPO_ID}"

# Créer le pool LXD
garm-cli pool add \
  --repo           "${REPO_ID}" \
  --provider-name  "lxd_local" \
  --image          "ubuntu:24.04" \
  --flavor         "default" \
  --os-type        "linux" \
  --os-arch        "amd64" \
  --max-runners    3 \
  --min-idle-runners 0 \
  --tags           "ubuntu,lxd" \
  --runner-prefix  "garm" \
  --enabled

# Vérifier
garm-cli pool list --repo "${REPO_ID}"

min-idle-runners à 0 pour le lab

Avec --min-idle-runners 0, GARM ne crée des runners que si un job est en attente. En production, vous pourriez mettre 1 pour avoir un runner toujours prêt et réduire le temps de démarrage du premier job.

Étape 8, Configurer le webhook Gitea

Gitea doit notifier GARM quand un job Actions est mis en file d'attente. Cette notification s'appelle un webhook workflow_job. L'URL cible est fournie par GARM (Controller Webhook URL).

1. Récupérer l'URL du webhook contrôleur :

   9997/webhooks/f3737450-c29c-4180-a18b-e2298f8d327f

   garm-cli controller show | grep "Controller Webhook URL"

2. Créer le webhook sur le repo :

   curl -X POST \
     -u 'giteaadmin:Admin1234!' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "gitea",
       "config": {
         "url":          "http://192.168.122.52:9997/webhooks/f3737450-c29c-4180-a18b-e2298f8d327f",
         "content_type": "json",
         "secret":       "garm-webhook-secret-lab2026"
       },
       "events": ["workflow_job"],
       "active": true
     }' \
     'http://localhost:3000/api/v1/repos/giteaadmin/garm-test/hooks'

   Le secret webhook doit correspondre

   Le secret dans le webhook Gitea doit être identique à --webhook-secret utilisé lors de garm-cli repository add. GARM vérifie la signature HMAC de chaque webhook reçu.

3. Vérifier le webhook :

   curl -s \
     -u 'giteaadmin:Admin1234!' \
     'http://localhost:3000/api/v1/repos/giteaadmin/garm-test/hooks' | \
     python3 -c "import sys,json; [print(h['id'], h['active'], h['events']) for h in json.load(sys.stdin)]"
   # → 1 True ['workflow_job']

Étape 9, Tester avec un workflow Actions

Créez un workflow qui demande un runner avec le label lxd (celui assigné au pool) :

.gitea/workflows/test-garm.yml

name: Test GARM Runner
on: [push]

jobs:
  test:
    runs-on: ["self-hosted", "lxd"]
    steps:
      - name: Infos runner
        run: |
          echo "Hostname: $(hostname)"
          echo "Kernel:   $(uname -r)"
          echo "Distro:   $(cat /etc/os-release | grep PRETTY_NAME)"
          echo "User:     $(whoami)"
      - name: Test réseau
        run: curl -sf https://gitea.com/api/swagger | head -5

Poussez ce fichier dans votre repo et observez dans une autre fenêtre :

# Surveiller les runners créés par GARM
watch garm-cli runner list --pool "$(garm-cli pool list --repo ${REPO_ID} --format json | \
  python3 -c 'import sys,json; pools=json.load(sys.stdin); print(pools[0]["id"])')"

# Suivre les logs GARM
sudo journalctl -u garm -f --no-pager

Ce qui doit se passer

1. Le push déclenche le workflow Gitea Actions
2. Gitea envoie un webhook workflow_job queued à GARM
3. GARM crée un conteneur LXD ubuntu:24.04
4. GARM installe et démarre l'agent act_runner dans le conteneur
5. L'agent s'enregistre sur Gitea
6. Gitea assigne le job au runner
7. Le job s'exécute (quelques secondes)
8. GARM détruit le conteneur

Le délai entre la détection du job et le démarrage du runner est typiquement de 30 à 90 secondes (temps de téléchargement de l'image ubuntu:24.04 au premier lancement, puis quelques secondes si l'image est en cache).

Vérification complète

# État du contrôleur
garm-cli controller show

# Providers
garm-cli provider list

# Endpoints Gitea
garm-cli gitea endpoint list

# Credentials
garm-cli gitea credentials list

# Repos gérés
garm-cli repository list

# Pools
garm-cli pool list --all

# Runners actifs
garm-cli runner list --all

Dépannage

Symptôme	Cause probable	Action
Pool manager false après ajout repo	PAT incorrect ou endpoint mal configuré	journalctl -u garm -n 30
Webhook not received	Mauvaise URL ou secret incorrect	Vérifier l'URL du Controller Webhook dans garm-cli controller show
Runner créé mais job ne s'assigne pas	Labels du pool ne correspondent pas à runs-on	Pool avec tag lxd, workflow avec runs-on: ["self-hosted", "lxd"]
Container LXD timeout	Image ubuntu:24.04 non en cache	Premier lancement long : attendre 2-3 min, augmenter runner-bootstrap-timeout
garm-cli: permission denied sur config	Config créée par root	sudo chown $USER ~/.local/share/garm-cli/config.toml
Token JWT expiré	Session expirée	garm-cli profile login -u garmadmin -p "mot-de-passe"

Glissez pour voir

À retenir

• GARM v0.2.0 gère les credentials Gitea via garm-cli gitea credentials add.
• Le webhook workflow_job est l'événement déclencheur, sans lui, GARM ne crée aucun runner.
• Le secret webhook doit correspondre entre le hook Gitea et garm-cli repository add.
• Chaque runner est éphémère et associé à un seul job.
• Les labels du pool (--tags) doivent correspondre aux runs-on du workflow.

Prochaines étapes

Retour à la section GARM Architecture, concepts, prérequis.

Installer Gitea Si vous n'avez pas encore Gitea, suivez le guide d'installation complet.

×

📖 Voir la documentation →