Chimera
Un runner GitHub Actions riscritto da zero, e la prima documentazione pubblica del protocollo che lo governa.
Chimera è un sostituto drop-in dei self-hosted runner di GitHub Actions: un singolo binario in Rust che gestisce più runner in parallelo, eseguibile come servizio systemd, in un container Docker o semplicemente da terminale. Parla lo stesso protocollo di registrazione ed esecuzione dei job del runner ufficiale, quindi funziona con qualsiasi workflow esistente senza modifiche.
La parte più interessante del progetto, però, non è il rewrite. È ciò che è stato necessario produrre per realizzarlo.
Il problema
I runner self-hosted ufficiali sono lenti, pesanti in termini di risorse, soffrono di memory leak e sono scomodi da gestire. Ogni runner è un processo separato, con la propria configurazione e il proprio servizio da monitorare. In un'organizzazione con decine di runner distribuiti su più macchine, l'overhead operativo diventa significativo: aggiornamenti da propagare, workspace da ripulire, container e processi orfani che sopravvivono alla fine del job.
Chimera nasce per rendere questa esperienza migliore, con un focus su performance, affidabilità e gestione multirunner.
Il protocollo, documentato per la prima volta
Il runner ufficiale di GitHub è open source, ma il protocollo che parla non lo è. Non esiste una specifica, né un riferimento agli endpoint, né una descrizione dei formati con cui runner e backend si scambiano job, log e stato. L'unico modo per capirlo è leggere l'implementazione e osservare il traffico.
Reimplementare quel comportamento in Rust ha significato ricostruire il protocollo pezzo per pezzo. Quel lavoro è diventato una specifica pubblica di oltre 1500 righe, rilasciata insieme al codice: l'intero ciclo di vita di un runner, dalla registrazione all'autenticazione, dal polling dei job allo streaming dei log, fino al completamento: endpoint, payload, formati e comportamenti non ovvi.
Quello che ne emerge è un protocollo stratificato da anni di migrazioni: tre servizi backend distinti, due generazioni di API che convivono e vengono scelte job per job, tre tipi di token diversi in circolazione, e un formato di serializzazione interno tutto suo. Molti dettagli non falliscono in modo rumoroso ma silenzioso: un timestamp con la precisione sbagliata non genera errori, genera semplicemente una UI che mostra dati scorretti.
È materiale utile a chiunque debba integrarsi con Actions, costruire tooling di CI o capire cosa sta succedendo quando un runner smette di comportarsi come previsto. Ad oggi non esiste altro di equivalente.
Cosa significa "drop-in"
La compatibilità non è parziale. Chimera supporta l'esecuzione degli step su host e in container, tutti i tipi di action (Node.js, Docker, composite), l'intero sistema di espressioni ${{ }}, tutti i workflow command, condizioni, timeout, continue-on-error, cancellazione, streaming live dei log verso la UI di GitHub e actions/cache.
La registrazione avviene esattamente come con il runner ufficiale: stesso token, stessi label:
chimera register --url https://github.com/org/repo --token AABBC... --name runner-0
chimera register --url https://github.com/org/repo --token DDEEF... --name runner-1
chimera startDa lì in poi i runner fanno polling concorrente, ognuno con un workspace pulito per ogni job.
In più
Un singolo processo gestisce tutti i runner, con isolamento degli errori: il fallimento di uno non trascina gli altri. La pulizia di workspace, container e processi orfani è automatica. E il caching non passa più dal servizio remoto di GitHub: Chimera espone un server di cache locale compatibile con actions/cache, che rende le hit immediate senza alcuna modifica ai workflow.
Limiti
GitHub Enterprise Server non è supportato e Windows non rientra nello scope. Va inoltre considerato che il protocollo su cui il progetto si appoggia, non essendo documentato ufficialmente, può cambiare senza preavviso: è il trade-off implicito di qualunque implementazione compatibile, ed è una delle ragioni per cui la specifica è mantenuta insieme al codice e non separatamente.
Open source
Chimera è rilasciato con licenza MIT. Oltre a essere uno strumento utilizzabile in produzione, vuole essere una reference implementation leggibile del protocollo dei GitHub Actions runner: codice e specifica si validano a vicenda, e chiunque può verificare, correggere o estendere entrambi.