Runner Forgejo su Codeberg: guida pratica per il CI/CD self-hosted

Perché auto-hostare il tuo runner CI/CD?

Se stai valutando Codeberg come alternativa a GitHub, probabilmente hai già capito che si tratta di un'ottima piattaforma. Sviluppata su Forgejo e gestita da un'organizzazione no-profit, offre un ambiente rispettoso della privacy e orientato alla comunità. Tuttavia, come tutte le infrastrutture condivise gestite da realtà senza fini di lucro, anche i runner di Codeberg hanno dei limiti.

La soluzione? Ospitare il proprio runner Forgejo. Il vantaggio è che i runner avviano le connessioni in uscita verso Codeberg, quindi funzionano senza problemi su un VPS, un server casalingo o anche sul portatile. Non serve aprire porte sul firewall.

Come funziona l'architettura

Prima di passare alla configurazione, vale la pena capire cosa stiamo costruendo. Un Forgejo runner è un processo che riceve i job da Codeberg e li esegue. Per motivi di sicurezza, lo isoliamo dal sistema host usando Docker-in-Docker (DinD). In questo modo il runner crea ambienti containerizzati senza toccare il demone Docker della macchina ospite.

Configurare Docker Compose

La base del setup è un sistema semplice a due container:

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'

In pratica, un container fornisce l'ambiente Docker isolato e l'altro è il runner che comunica con esso.

Preparare il sistema

Prima di avviare i container, bisogna creare la struttura delle directory con le giuste permessi. Ti consiglio di usare /opt/forgejo-runner come directory principale. Poi esegui:

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

Quindi genera il file di configurazione predefinito:

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

Registra il runner su Codeberg

Ora arriva l'intreccio con la piattaforma. Vai nelle impostazioni del tuo account (o organizzazione) su Codeberg, trova la sezione Actions → Runners e clicca su "Create new runner". Scegli un nome e una descrizione, e Codeberg ti fornirà un UUID e un Token.

Mettili da parte subito, perché spariranno dopo la prima visione. Questi due valori sono il legante che permette al runner di collegarsi a Codeberg.

Impostare labels e capacity

In runner-config.yml serve due interventi principali:

1. Autenticazione Inserisci i valori di UUID e Token nella sezione server.

2. Labels Le labels sono il modo in cui i workflows trovano il tuo runner. Ad esempio:

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

Se un workflow richiede runs-on: ubuntu-latest, Codeberg lo assegna al runner che possiede quella label.

Optional: Capacity Il runner gestisce di default un solo job. Se hai risorse sufficienti, puoi aumentare la capacity per permettere parallelismo. Per la maggior parte dei casi, 4 è un buon valore di partenza.

Avvia il runner

Quando il file di configurazione è completo, puoi avviarlo:

docker-compose up -d

Monitora i log per vedere se il runner si è registrato:

docker-compose logs -f runner

I vantaggi che avrai

Auto-hostare il runner ti permette di:

• Eliminare le code e ottenere tempi di esecuzione più veloci
• Avere pieno controllo sull'ambiente e sulle dipendenze
• Risparmiare sui costi e aiutare Codeberg a gestire la sua infrastruttura
• Mantenere i log dei workflows su server personali
• Scalare facilmente quando le esigenze crescono

Conclusione

Configurare un runner Forgejo self-hosted è un progetto che porta risultati subito. È abbastanza semplice da fare in un pomeriggio, yet powerful enough to scale with your development team.