GARM : orchestrer des runners GitHub/Gitea Actions avec LXD

Vous avez des pipelines GitHub Actions ou Gitea Actions, mais vos runners self-hosted sont statiques — ils tournent en permanence, coûtent de l’argent et doivent être maintenus manuellement. GARM (GitHub/Gitea Actions Runner Manager) résout ce problème : il crée et détruit automatiquement des runners à la demande, sur LXD, KVM, AWS, Azure ou GCP.

Quand un job Actions est mis en file d’attente, GARM reçoit un webhook du serveur (GitHub ou Gitea), démarre un conteneur ou une machine virtuelle, y installe l’agent runner, et l’enregistre. Une fois le job terminé, la VM est détruite. Pas de runner zombi, pas de surcoût.

Ce que vous trouverez dans cette section

Installer GARM avec LXD Extraction depuis l'image Docker nightly, configuration systemd, provider LXD sur Ubuntu 24.04.

Intégrer GARM avec Gitea Endpoint Gitea, credentials PAT, repo, pool LXD, webhook workflow_job — de zéro à un runner fonctionnel.

Comment fonctionne GARM

GARM joue le rôle d’un orchestrateur de runners. Il s’intercale entre le serveur de forge (GitHub ou Gitea) et le fournisseur d’infrastructure (LXD, cloud public…).

Le flux d’un job Actions

Gitea                    GARM                     LXD
  │                        │                        │
  │──workflow_job queued──▶│                        │
  │      (webhook)         │                        │
  │                        │──crée conteneur───────▶│
  │                        │◀──IP + état ready──────│
  │                        │                        │
  │                        │  installe runner agent │
  │                        │  dans le conteneur     │
  │                        │                        │
  │◀──runner s'enregistre──│                        │
  │                        │                        │
  │──assigne job──────────▶│  runner exécute le job │
  │                        │                        │
  │──workflow_job completed▶│                        │
  │      (webhook)         │──détruit conteneur────▶│

Le runner est éphémère : il est créé pour ce job précis, et détruit dès que le job est fini. Chaque job repart d’un environnement propre, sans résidus des exécutions précédentes.

Concepts clés

Concept	Rôle
Controller	L’instance GARM centrale. Gère les providers, les endpoints, les pools.
Provider	Le backend d’infrastructure : LXD, Openstack, AWS, GCP, Azure…
Endpoint	La forge (Gitea ou GitHub) à laquelle GARM se connecte.
Credentials	Le token d’authentification (PAT Gitea ou GitHub App).
Pool	Association entre une forge (repo/org/enterprise), un provider et une image. Définit le nombre max/min de runners.
Runner	La VM ou le conteneur créé par le provider pour exécuter un job.

Architecture d’un déploiement lab

Dans ce guide, GARM est installé sur la même VM que Gitea pour simplifier le lab. En production, GARM et Gitea seraient sur des serveurs distincts.

┌─────────────── gitea-lab (192.168.122.52) ───────────────┐
│                                                           │
│  ┌─────────────────┐     webhook     ┌─────────────────┐ │
│  │                 │────────────────▶│                 │ │
│  │  Gitea :3000    │                 │  GARM :9997     │ │
│  │                 │◀────────────────│                 │ │
│  └─────────────────┘   enregistrement│  Provider: LXD  │ │
│                                      └────────┬────────┘ │
│                                               │          │
│                                    crée/détruit containers│
│                                               ▼          │
│                              ┌──────────────────────────┐│
│                              │  LXD (snap 5.21 LTS)     ││
│                              │  ubuntu:24.04             ││
│                              │  [runner-xxx] (éphémère)  ││
│                              └──────────────────────────┘│
└───────────────────────────────────────────────────────────┘

Prérequis

Avant de commencer, vous avez besoin de :

Une VM Ubuntu 24.04 avec au moins 4 Go de RAM et 30 Go de disque (les containers LXD en ont besoin)
Gitea ≥ 1.24 installé et accessible (voir Installer Gitea)
Docker installé sur votre machine locale (pour extraire les binaires GARM de l’image nightly)
Les droits sudo sur la VM

À retenir

GARM crée des runners à la demande, sur webhook workflow_job queued.
Chaque runner est éphémère : créé pour un job, détruit après.
Le provider LXD permet de lancer des conteneurs Ubuntu directement sur la VM, sans cloud public.
GARM supporte GitHub, Gitea (≥ v0.2.0), et d’autres forges.
La configuration se fait via garm-cli ou l’API REST.

Prochaines étapes

Installer GARM avec LXD Extraction des binaires, service systemd, vérification de l'API.

Intégrer GARM avec Gitea Configurer l'endpoint, les credentials, le pool et le webhook.