Pipeline

Una pipeline prende un commit da un repository Git e lo porta in esecuzione su questa macchina. Ha due fasi, entrambe opzionali: costruzione e rilascio. Gli step vengono eseguiti in ordine; il primo che fallisce ferma tutto, salvo quelli marcati “prosegui anche se fallisce”.

Collegare un repository

In Repository → Collega repository:

• URL: https://github.com/acme/api.git oppure git@github.com:acme/api.git.
• Accesso:
  • pubblico: nessuna credenziale;
  • token HTTPS: su GitHub crea un fine-grained token con permesso “Contents: read” e usa x-access-token come nome utente; su GitLab usa un deploy token;
  • chiave SSH: incolla la chiave privata di una deploy key in sola lettura.

La credenziale viene cifrata prima di essere salvata e non è più leggibile dall’interfaccia. In modifica, lasciare il campo vuoto mantiene quella esistente.

Dove finisce il checkout

Ogni repository ha un checkout persistente in <SIRIO_DATA_DIR>/workspaces/<nome> (di default /var/lib/sirio/workspaces/<nome>), riusato fra un’esecuzione e l’altra: la prima volta è un git clone, le successive solo fetch + checkout sul commit richiesto. Non viene mai ricreato da zero a meno di essere cancellato a mano.

<nome> deriva dal nome del repository al momento del collegamento: in minuscolo, con tutto ciò che non è lettera, cifra o _ trasformato in - (My App → my-app), e un suffisso -2, -3, … se un altro repository finisce già nella stessa directory. La pagina Repository lo mostra sotto ciascun nome. Viene scelto una volta sola e non segue le rinomine successive, perché è anche il nome che Compose usa come progetto quando il file di uno step compose sta nella root del checkout — e quindi il prefisso dei container che crea (my-app-web-1). Spostarlo farebbe partire al deploy successivo una seconda copia dello stack accanto a quella vecchia. Per lo stesso motivo, i repository collegati prima di questa convenzione mantengono la loro directory repo-<id>.

Il pulsante Rileva da compose nell’editor della pipeline, invece, non tocca questo checkout: fa una clone superficiale ed effimera in una sottocartella temporanea della stessa workspaces/, solo per cercare compose.yaml/compose.yml/docker-compose.yaml/docker-compose.yml nella root, e la cancella subito dopo — non esegue né legge altro dal repository.

Tipi di step

Comando shell

Eseguito con sh -c nella cartella del checkout. Variabili disponibili:

Variabile	Contenuto
SIRIO_COMMIT	sha completo del commit
SIRIO_COMMIT_SHORT	primi 7 caratteri
SIRIO_REF	ref completo, es. refs/heads/main
SIRIO_BRANCH	nome del branch
SIRIO_RUN_ID	numero dell’esecuzione
SIRIO_PIPELINE, SIRIO_REPOSITORY	nomi configurati
SIRIO_WORKSPACE	percorso del checkout
DOCKER_HOST	socket Docker configurato

npm ci
npm run build

Build immagine Docker

Esegue docker build. Nel tag sono espansi i segnaposto {{commit}}, {{commit_short}}, {{branch}}, {{run}}, {{pipeline}}, {{repository}}:

acme/api:{{commit_short}}

Dockerfile e contesto sono relativi alla cartella della pipeline.

Docker Compose

Esegue docker compose con un sottocomando fra up, down, pull, build, restart, stop. Con up Sirio aggiunge --detach --remove-orphans, con down --remove-orphans.

Gli argomenti aggiuntivi (es. --pull always --wait) vengono accodati dopo questi, divisi sugli spazi e passati a docker compose come argomenti separati, senza shell: le virgolette non vengono interpretate, quindi un singolo argomento non può contenere spazi. L’editor mostra il comando completo così come verrà eseguito.

Riavvio container

Riavvia un container per nome tramite l’Engine API, senza passare dalla CLI. Il nome accetta gli stessi segnaposto del tag immagine.

Backup

Esegue uno dei piani di backup del sito e aspetta lo snapshot: messo prima degli step di deploy, salva il sito com’era prima che il deploy lo modifichi. Richiede che la pipeline sia collegata a un sito e un piano di quel sito, e fa fallire l’esecuzione se il backup fallisce. Vedi docs/it/backup.md. Una pipeline esportata conserva l’ID del piano, che su un’altra istanza non significa nulla: dopo averla importata lì, scegli di nuovo il piano.

Avvio automatico da webhook

Imposta il trigger su push o tag e indica branch o pattern (main, release/*, v*). Alla creazione Sirio genera il secret e lo mostra una sola volta.

Sul provider Git configura:

• URL: quello indicato nella scheda Webhook della pipeline;
• Content type: application/json;
• Secret: quello generato;
• Eventi: solo push.

Se hai perso il secret, generane uno nuovo dalla stessa scheda e aggiornalo sul provider.

Chiamate con firma assente o errata ricevono 401 e finiscono nel registro attività. Chiamate valide ma su un ref che non corrisponde al trigger ricevono 200 con esito “ignorato”.

Esecuzione e log

Le esecuzioni sono seriali: una alla volta, in coda. Su una singola macchina due deploy simultanei fanno più danni che altro.

Ogni run mostra il log in tempo reale (WebSocket) e lo conserva su disco. Le righe sono distinte per origine: system (Sirio), stdout, stderr. Vengono conservate le ultime 50 esecuzioni per pipeline, poi log e record più vecchi vengono rimossi.

Rollback

Ripeti questo commit su un’esecuzione precedente riesegue la pipeline sullo stesso sha, non sull’ultimo commit del branch. È il modo più semplice di tornare indietro: la stessa sequenza di build e rilascio, sul codice che funzionava.

Perché sia davvero un rollback, gli step non devono dipendere da latest: usa {{commit_short}} nei tag immagine, così ogni versione resta distinta e riproducibile.

Override delle variabili d’ambiente

Un deploy ricrea i container a partire dall’immagine e dal compose file, quindi una variabile cambiata a mano su un container in esecuzione si perde al push successivo. Per mantenerla, impostala dal pannello: Override variabili (pulsante a ingranaggio nella lista dei container, o nella pagina del container), una KEY=valore per riga. Un override aggiunge una variabile o sostituisce il valore impostato dall’immagine o dal compose file: utile per un secret che non vuoi nel repository, o per un flag di debug su un solo host.

Il salvataggio applica subito la modifica ricreando il container (con una breve interruzione). Il resto della configurazione resta com’è: mount e volumi, compresi quelli anonimi che un’immagine dichiara con VOLUME, reti e relativi alias, così gli altri servizi di un progetto compose lo raggiungono ancora per nome, restart policy, label. Salvare una lista invariata non riavvia nulla.

Gli override sono salvati nel database di Sirio per nome del container, non per ID, e riapplicati dopo ogni esecuzione riuscita: una pipeline che ricrea il container li ritrova subito, prima del riallineamento del proxy. I container che li hanno già non vengono toccati. Nella scheda Ambiente del container, le variabili impostate così hanno il badge override.

Rimuovere un override si comporta diversamente a seconda di chi gestisce il container:

• gestito da Compose: Sirio lo fa prima ricreare a Compose da compose file e .env, poi applica gli override rimasti, così torna il valore originale. Compose gira con l’utente di Sirio, quindi deve poter leggere ogni file del progetto: un env_file creato da root con permessi 0600 lo blocca, e l’errore indica il file (chgrp sirio FILE && chmod g+r FILE lo risolve — l’utente sirio controlla già Docker, quindi non gli dà nulla che non potesse raggiungere);
• qualsiasi altro container: non c’è una fonte da cui recuperare il valore precedente, quindi resta l’ultimo applicato. Se ti serve quello di prima, impostalo esplicitamente.

Un override non può eliminare una variabile definita dall’immagine o dal compose file, solo cambiarne il valore. I nomi seguono la regola consueta: lettere, cifre e _, senza iniziare con una cifra. I valori sono salvati in chiaro, come Docker stesso conserva l’ambiente di un container; modificarli richiede il permesso di modifica sui container.

Esportazione e importazione

Esporta nella pagina Pipeline scarica in un unico file JSON tutte le pipeline che vedi; l’icona di download su una riga esporta solo quella. Importa rilegge un file del genere, su questa istanza o su un’altra, e mostra ogni pipeline prima di creare qualsiasi cosa:

• il repository viene proposto confrontando l’URL Git originale (poi il nome), e va scelto quando non corrisponde nulla: gli ID non hanno senso tra istanze diverse, quindi il file si limita a descriverlo;
• il sito viene proposto per nome, altrimenti quello del repository scelto;
• il nome si può cambiare, visto che dev’essere unico nel repository.

L’importazione è tutto o niente: se una pipeline viene rifiutata (step non validi, nome già usato, un sito in cui non puoi creare pipeline) non ne viene creata nessuna e viene indicata la riga responsabile.

I secret dei webhook non vengono mai esportati. Una pipeline con trigger push o tag riceve un secret nuovo all’importazione, mostrato una sola volta alla fine insieme al nuovo URL: aggiorna entrambi sul provider Git. Tutto il resto viaggia così com’è, variabili d’ambiente degli step e build arg compresi, quindi tratta il file come la configurazione che è.

{
  "format": "sirio-pipelines",
  "version": 1,
  "exported_at": "2026-10-15T09:30:00Z",
  "pipelines": [
    {
      "name": "deploy",
      "enabled": true,
      "trigger_type": "push",
      "trigger_ref": "main",
      "workdir": "",
      "build_steps": [{ "name": "test", "type": "shell", "command": "go test ./..." }],
      "deploy_steps": [{ "name": "up", "type": "compose", "compose_command": "up" }],
      "repository": { "name": "api", "git_url": "https://github.com/acme/api.git" },
      "site": { "name": "acme" }
    }
  ]
}

Gli stessi endpoint funzionano da script, con una sessione: GET /api/pipelines/export (facoltativamente ?ids=1,2) e POST /api/pipelines/import con il documento qui sopra, dando a ogni voce un repository_id e facoltativamente un site_id.

Esempio completo

Repository acme/api, deploy con compose a ogni push su main.

Costruzione

1. test — shell: go test ./...
2. immagine — build docker, tag acme/api:{{commit_short}}, Dockerfile Dockerfile

Rilascio

1. tag corrente — shell: docker tag acme/api:$SIRIO_COMMIT_SHORT acme/api:corrente
2. avvio — compose up, file docker-compose.yml

Con docker-compose.yml che punta a acme/api:corrente, il rollback consiste nel ripetere una esecuzione precedente: ritagga l’immagine di quel commit e riavvia lo stack.