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

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

Mag 22, 2026 codeberg forgejo ci-cd docker self-hosting github-alternative devops automation

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.

Hai un'idea? Trova il dominio perfetto per lei

Il nostro generatore di nomi di dominio con AI suggerisce nomi disponibili tra centinaia di estensioni. SSL, DNS e privacy Whois gratuiti inclusi.

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.

Hai un'idea? Trova il dominio perfetto per lei

Il nostro generatore di nomi di dominio con AI suggerisce nomi disponibili tra centinaia di estensioni. SSL, DNS e privacy Whois gratuiti inclusi.

Leggi in altre lingue:

BG CS DA DE EL EN ES FI FR HU NB NL PL PT RO RU SV TR UZ ZH-HANS