Forgejo Runner sur Codeberg : guide pratique pour un CI/CD 100 % perso

Pourquoi héberger son propre runner CI/CD ?

Si vous cherchez une alternative à GitHub, Codeberg mérite votre attention. Cette plateforme, construite sur Forgejo et gérée par une association, propose un environnement respectueux de la vie privée. Mais comme toute infrastructure partagée, elle a ses limites en termes de capacité.

La solution ? Héberger son propre runner Forgejo. L’avantage principal : les runners se connectent vers l’extérieur. Ils fonctionnent donc sans configuration réseau particulière, que ce soit sur un VPS, un serveur à domicile ou même un simple ordinateur portable.

Comment ça marche ?

Un runner Forgejo agit comme un exécuteur de tâches. Il récupère les jobs depuis Codeberg et les lance dans des conteneurs isolés. Pour renforcer la sécurité, on utilise Docker-in-Docker (DinD). Le runner dispose ainsi de son propre environnement Docker, sans toucher au démon Docker de l’hôte.

Configuration avec Docker Compose

Voici une configuration simple à deux conteneurs :

version: '3.8'

services:
  docker-in-docker:
    image: docker:dind
    container_name: 'docker_dind'
    privileged: 'true'
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: 'unless-stopped'

  runner:
    image: 'data.forgejo.org/forgejo/runner:12'
    links:
      - docker-in-docker
    depends_on:
      docker-in-docker:
        condition: service_started
    container_name: 'runner'
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: 'unless-stopped'
    command: 'forgejo-runner daemon --config runner-config.yml'

Le premier conteneur fournit un environnement Docker isolé. Le second exécute le runner et communique avec lui.

Préparer le système

Avant de lancer les conteneurs, créez la structure de dossiers et appliquez les bonnes permissions. Placez-vous dans /opt/forgejo-runner et exécutez :

cd /opt/forgejo-runner
mkdir -p data/.cache
chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache

Puis générez le fichier de configuration :

sudo sh -c 'docker run --rm data.forgejo.org/forgejo/runner:12 forgejo-runner generate-config > data/runner-config.yml'

Ce document bien commenté sert de base pour la configuration finale.

Enregistrer le runner auprès de Codeberg

Dans les paramètres de votre compte ou organisation sur Codeberg, allez dans Actions → Runners. Cliquez sur « Create new runner », donnez un nom et une description.

Codeberg génère alors un UUID et un token. Notez-les tout de suite, car ils n’affichent pas de nouveau sans réinitialisation. La plateforme vous affiche aussi la section YAML à copier dans votre configuration.

Définir des labels et ajuster la capacité

Dans runner-config.yml, deux réglages sont essentiels :

1. Authentification :
Ajoutez les données fournies par Codeberg dans la section server.

2. Labels :
Les labels permettent aux workflows de trouver votre runner. Ils suivent une syntaxe simple :

labels: 
  - 'ubuntu-latest:docker://node:20-bookworm'
  - 'ubuntu-22.04:docker://node:20-bookworm'
  - 'ubuntu-24.04:docker://node:22-bookworm'

当一个 workflow specifies runs-on: ubuntu-latest, il est automatiquement attribué à votre runner.

Optional: Adjust Capacity By default, runners handle one job at a time. If you have resources, increase the capacity setting to run multiple jobs simultaneously—we recommend starting at 4 for most setups.

Démarrage et vérification

On et la configuration est terminé, la