Forgejo Runner

Le rôle Forgejo Runner permet d’installer et de configurer le composant chargé d’exécuter les workflows CI/CD de Forgejo.

Il est responsable de :

installer et configurer Forgejo Runner ;
vérifier les fichiers et leurs permissions ;
créer les répertoires nécessaires ;
construire l’image Docker utilisée par le runner ;
déployer la configuration du runner ;
créer et configurer les secrets nécessaires ;
enregistrer le runner auprès de Forgejo ;
démarrer le runner dans un conteneur Docker.

Le Forgejo Runner est un composant de l’écosystème Forgejo permettant d’exécuter les workflows définis dans les fichiers présents dans les dépôts.

Il permet notamment d’automatiser :

la compilation d’une application ;
l’exécution des tests ;
l’analyse du code ;
la création d’artefacts ;
la génération d’images Docker ;
le déploiement d’une application.

Fonctionnement

Forgejo Runner fonctionne dans son propre conteneur Docker.

Lorsqu’un commit contenant une modification d’un workflow est envoyé sur un dépôt Forgejo, Forgejo détecte le workflow et crée un job à exécuter.

Le runner enregistré auprès de Forgejo récupère ensuite ce job et exécute les différentes étapes définies dans le workflow.

Le fonctionnement peut être résumé ainsi :

Développeur
     │
     │ git push
     ▼
  Forgejo
     │
     │ Détection du workflow
     ▼
  Job CI/CD
     │
     │ Attribution au runner
     ▼
Forgejo Runner
     │
     │ Exécution du workflow
     ▼
Environnement Docker
     │
     ├── Build
     ├── Tests
     ├── Packaging
     └── Artefacts
     │
     ▼
  Résultat du job
     │
     ▼
  Forgejo

L’interface Forgejo permet ensuite de consulter l’état du workflow ainsi que les logs de chaque étape.

Structure du rôle

roles/forgejo_runner/
├── defaults/
│   └── main.yml                 # Variables par défaut du rôle
├── files/
│   └── runner-image/
│       └── Dockerfile           # Image de l'environnement d'exécution
├── tasks/
│   └── main.yml                 # Point d'entrée et exécution des différentes étapes
└── templates/
    ├── config.yml.j2             # Configuration du Forgejo Runner
    └── docker-compose.yml.j2     # Configuration Docker Compose du runner

Variables

Les variables du rôle sont définies dans :

roles/forgejo_runner/defaults/main.yml

Elles permettent de modifier la configuration du runner sans avoir à modifier directement les tâches Ansible.

Variables globales

Variable	Description
`forgejo_runner_name`	Nom donné au runner
`forgejo_runner_image`	Image Docker utilisée pour le conteneur du runner
`forgejo_runner_labels`	Labels permettant de définir les environnements auxquels le runner peut répondre

Les valeurs par défaut peuvent être surchargées par les variables d’inventaire ou du playbook.

Déploiement

Lors de l’exécution du rôle Ansible, les opérations sont réalisées dans un ordre permettant de préparer complètement le runner avant son démarrage.

Le rôle effectue notamment les opérations suivantes :

définir les chemins utilisés par le runner ;
construire l’image Docker nécessaire à l’environnement du runner ;
créer les répertoires nécessaires ;
vérifier les permissions des fichiers et répertoires ;
générer la configuration du runner ;
créer les fichiers nécessaires à son fonctionnement ;
déployer le fichier docker-compose.yml ;
créer ou configurer les secrets nécessaires ;
enregistrer le runner auprès de Forgejo ;
démarrer le conteneur du runner.

Le runner doit être enregistré auprès de Forgejo avant de pouvoir récupérer et exécuter des workflows.

Vérifications

Après l’exécution du rôle Ansible, plusieurs vérifications permettent de s’assurer que le runner fonctionne correctement.

1. Vérifier que le conteneur fonctionne

Vérifier que le conteneur Forgejo Runner est démarré :

docker ps --filter "name=forgejo-runner"

Le conteneur doit apparaître avec un état similaire à :

Up ...

Pour afficher également les conteneurs arrêtés :

docker ps -a --filter "name=forgejo-runner"

Si le conteneur est arrêté ou redémarre continuellement, consulter les logs.

2. Vérifier les logs

Afficher les logs du runner :

docker logs forgejo-runner

Afficher uniquement les 100 dernières lignes :

docker logs --tail 100 forgejo-runner

Suivre les logs en temps réel :

docker logs -f forgejo-runner

Les logs permettent notamment de vérifier :

le démarrage du runner ;
sa connexion à Forgejo ;
son enregistrement ;
la récupération des jobs ;
l’exécution des workflows ;
les éventuelles erreurs de configuration.

3. Vérifier l’identité utilisée dans le conteneur Forgejo

Cette vérification permet de connaître l’utilisateur utilisé par le processus exécuté dans le conteneur Forgejo :

docker exec forgejo whoami

Dans cette configuration, la réponse attendue est :

root

Cette commande concerne le conteneur Forgejo et non le conteneur Forgejo Runner. Elle permet de vérifier le contexte d’exécution du conteneur Forgejo.

4. Vérifier la disponibilité du CLI Forgejo

Le CLI fourni par Forgejo peut être utilisé pour administrer certaines fonctionnalités depuis le conteneur Forgejo.

Vérifier qu’il est disponible :

docker exec -u git forgejo forgejo forgejo-cli --help

Vérifier les commandes liées aux Actions :

docker exec -u git forgejo forgejo forgejo-cli actions --help

Vérifier les commandes d’enregistrement :

docker exec -u git forgejo forgejo forgejo-cli actions register --help

Les commandes disponibles doivent notamment permettre de retrouver des opérations telles que :

generate-runner-token
generate-secret
register

Les commandes disponibles peuvent varier selon la version de Forgejo utilisée. La sortie de --help doit donc être considérée comme la référence pour la version installée.

5. Vérifier l’enregistrement du runner

Le runner doit être enregistré auprès de Forgejo avant de pouvoir exécuter des workflows.

Une commande d’enregistrement peut être utilisée selon la configuration :

docker exec -u git forgejo forgejo forgejo-cli actions register \
  --name forgejo-runner \
  --secret "$RUNNER_SECRET"

Le secret utilisé pour l’enregistrement doit rester confidentiel.

Il ne doit notamment pas être :

écrit directement dans un dépôt Git ;
placé en clair dans un fichier versionné ;
affiché dans les logs ;
intégré directement dans une image Docker.

6. Vérifier la configuration du runner

Le fichier .runner contient les informations permettant au runner de connaître notamment son serveur Forgejo et son identité.

Vérifier son contenu :

docker exec forgejo-runner cat /data/.runner

La structure doit être similaire à :

server:
  connections:
    forgejo:
      url: https://ton-forgejo/
      uuid: ...
      token: ...

Les valeurs uuid et token sont des informations sensibles et ne doivent pas être publiées dans la documentation ou les logs.

Le nom et l’emplacement exacts du fichier peuvent dépendre de la version et de la configuration du runner.

7. Vérifier le runner depuis Forgejo

Depuis l’interface d’administration de Forgejo, vérifier que le runner apparaît comme enregistré et disponible.

Il faut notamment vérifier :

son nom ;
son état ;
ses labels ;
sa dernière connexion ;
sa capacité à accepter des jobs.

Cette vérification est importante car un runner peut être correctement démarré côté Docker mais ne pas être correctement connecté à Forgejo.

8. Exécuter un workflow de test

La meilleure vérification consiste à exécuter un workflow simple.

Par exemple, créer temporairement un workflow permettant simplement de vérifier l’environnement :

name: Runner test

on:
  push:

jobs:
  test:
    runs-on: docker

    steps:
      - name: Vérifier l'environnement
        run: |
          uname -a
          node --version
          docker --version

Le workflow doit apparaître dans l’interface Forgejo et être pris en charge par le runner.

Cette vérification permet de valider simultanément :

Forgejo
   │
   ▼
Workflow
   │
   ▼
Runner
   │
   ▼
Environnement d'exécution
   │
   ▼
Commandes
   │
   ▼
Résultat

Les images Docker utilisées par les workflows

Il est important de distinguer l’image du conteneur Forgejo Runner de l’environnement dans lequel les jobs sont exécutés.

Le runner lui-même fonctionne dans son propre conteneur Docker.

Cependant, les étapes d’un workflow peuvent nécessiter un environnement particulier : Node.js, .NET, Docker CLI, Python, etc.

Les images permettant de fournir ces environnements sont stockées dans :

roles/forgejo_runner/files/runner-image/

Par exemple :

roles/forgejo_runner/files/
└── runner-image/
    └── Dockerfile

Ces Dockerfiles permettent de créer des environnements adaptés aux besoins des workflows CI/CD.

Pourquoi créer une image personnalisée ?

Une image Docker standard peut ne pas contenir tous les outils nécessaires à un projet.

Par exemple, un projet peut nécessiter simultanément :

Node.js ;
npm ;
le SDK .NET ;
Git ;
Docker CLI ;
Docker Buildx ;
différents outils système.

Il est alors possible de créer une image personnalisée contenant exactement les dépendances nécessaires.

Cela permet d’obtenir un environnement :

reproductible ;
versionné ;
contrôlé ;
adapté au projet ;
indépendant de l’environnement du VPS.

Si un projet nécessite un environnement différent, une nouvelle image peut être créée plutôt que de modifier l’environnement utilisé par les autres workflows.

Exemple : projet Davai

L’application Davai utilise notamment :

actions/checkout@v4

et nécessite un environnement contenant Node.js pour les différentes étapes de son workflow.

Certaines étapes nécessitent également Docker.

Une image standard ne fournit pas nécessairement l’ensemble des outils nécessaires au workflow.

Une image personnalisée peut donc être construite afin de fournir l’environnement requis par le projet.

Cette approche permet également de faire évoluer l’environnement indépendamment du reste de l’infrastructure.

Dockerfile `full-builder`

Le Dockerfile full-builder constitue un environnement complet destiné aux workflows nécessitant plusieurs outils.

Il est basé sur :

node:20-bookworm

Des outils supplémentaires sont ensuite ajoutés, notamment Docker Buildx.

L’objectif est de disposer d’un environnement capable d’effectuer les différentes étapes du pipeline, par exemple :

Checkout
   │
   ▼
Installation des dépendances
   │
   ▼
Tests
   │
   ▼
Build
   │
   ▼
Docker Build
   │
   ▼
Publication / Artefacts

Labels du runner

Les labels permettent d’indiquer à Forgejo quels environnements peuvent être utilisés par un runner.

Un workflow peut demander un environnement particulier avec runs-on.

Par exemple :

jobs:
  build:
    runs-on: full-builder

Forgejo recherche alors un runner possédant le label correspondant.

Cette mécanique permet de disposer de plusieurs environnements d’exécution sur une même infrastructure.

Par exemple :

Forgejo
   │
   ├── Runner Linux
   │
   ├── Runner full-builder
   │
   └── Runner spécialisé .NET

Chaque runner ou environnement peut ainsi être utilisé uniquement pour les workflows auxquels il est adapté.

Maintenance

Lorsqu’un Dockerfile utilisé par les workflows est modifié, l’image doit être reconstruite puis redéployée.

Après modification :

modifier le Dockerfile ;
exécuter le rôle Ansible ;
reconstruire l’image ;
redémarrer le runner si nécessaire ;
vérifier les logs ;
exécuter un workflow de test.

Il est recommandé de versionner les Dockerfiles afin de pouvoir identifier précisément les outils et versions utilisés par un environnement de CI/CD.

Résumé des vérifications

Après le déploiement du rôle, les éléments suivants doivent être validés :

Forgejo Runner

Forgejo Runner

Fonctionnement

Structure du rôle

Variables

Variables globales

Déploiement

Vérifications

1. Vérifier que le conteneur fonctionne

2. Vérifier les logs

3. Vérifier l’identité utilisée dans le conteneur Forgejo

4. Vérifier la disponibilité du CLI Forgejo

5. Vérifier l’enregistrement du runner

6. Vérifier la configuration du runner

7. Vérifier le runner depuis Forgejo

8. Exécuter un workflow de test

Les images Docker utilisées par les workflows

Pourquoi créer une image personnalisée ?

Exemple : projet Davai

Dockerfile full-builder

Labels du runner

Maintenance

Résumé des vérifications

Dockerfile `full-builder`