Files
Febe/docs/processo.md
T
Alby96andClaude Opus 5.5 5e7cb73a85 CI: un'esecuzione a mano non annulla più la verifica del push
Il gruppo di concorrenza dipendeva solo dal ref: una verifica lanciata a mano su un ramo (per esempio con un seme, per
rifare un errore) annullava quella del push in corso sullo stesso ramo. In Gitea un lavoro annullato lascia sul commit
lo stato «failure» e workflow_dispatch non scrive stati, quindi la richiesta di unione restava bloccata sui controlli
richiesti. Ora l'evento fa parte del gruppo. Rilievo dispatch-annulla-push della revisione.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 12:04:55 +02:00

16 KiB

Processo: dal ramo al rilascio

Come una modifica arriva in main e da lì a una versione, con le stesse garanzie di un'azienda che non accetta codice non verificato. Vale per Alberto e per chiunque lavori al repository, persone o agenti. Repository: il Gitea di casa, https://gitea.encke-hake.ts.net/Alby96/Febe (non GitHub: niente strumenti di GitHub). Il motivo di ogni scelta è in docs/decisioni.md, alle righe del 20 ottobre 2026.

In breve

  1. Un ramo per filone di lavoro, nato da main.
  2. Commit piccoli e separati, ciascuno con un messaggio che dice che cosa cambia e perché.
  3. A ogni push la verifica parte da sola: controlli, prove, installatore, immagine.
  4. Una richiesta di unione per ramo, con il modello compilato, e una revisione.
  5. Si unisce in main solo con la verifica verde sull'ultimo commit (protezione di main), con un commit di unione; il ramo si cancella.
  6. Dopo l'unione la verifica gira su main e pubblica l'immagine :main e :sha-<commit>.
  7. Un rilascio è un tag vX.Y.Z su main.

Rami

  • Nome: <tipo>/<argomento>, in minuscolo, parole separate da trattini, in italiano. Tipi:

    Tipo Per
    funzione/ una funzione nuova (funzione/esporta-csv)
    correzione/ un difetto (correzione/webview2-avvio)
    urgente/ una correzione da rilasciare subito (vedi «Correzioni urgenti»)
    ci/ flussi, script e immagini della CI (ci/pipeline-aziendale)
    strumenti/ strumenti di sviluppo (strumenti/vscode)
    documenti/ solo documenti e guida
    rilascio/ la preparazione di una versione (rilascio/0.2.0)
  • Si parte da main aggiornato e si resta brevi: giorni, non settimane. Se main va avanti, il ramo si aggiorna (pulsante «Aggiorna il ramo» della richiesta di unione, o git merge origin/main) prima di unire.

  • Su main non si fa push diretto: ci si arriva solo da una richiesta di unione.

Commit

  • Piccoli e logici: ogni commit compila e passa le prove da solo (così git bisect funziona).
  • Messaggio in italiano: la prima riga (al massimo 72 caratteri) dice che cosa cambia; il corpo, dopo una riga vuota, dice perché. Non un elenco di file.
  • I commit scritti con un agente finiscono con una riga vuota e Co-Authored-By: … dell'agente.
  • Mai nel repository: risultati di compilazione (bin/, obj/, out/), segreti, campioni grezzi della sonda, dati di Alberto.

Richieste di unione

  • Una per ramo, con il modello (.gitea/pull_request_template.md): sintesi, perché, che cosa cambia, come è stato provato (comandi e risultati, e che cosa non è stato provato), rischi e ritorno indietro, le quattordici regole di §2 della specifica. Le righe per CHANGELOG.md e docs/stato.md stanno nella richiesta: le aggiunge chi integra.
  • Revisione: Alberto è il proprietario di tutto (.gitea/CODEOWNERS). Le osservazioni si risolvono con commit nuovi sullo stesso ramo, non riscrivendo quelli già rivisti.
  • Stile di unione: commit di unione («Crea un commit di unione»), con il titolo della richiesta; poi il ramo si cancella («Elimina il ramo dopo l'unione», da tenere attivo nelle impostazioni del repository).
  • Tornare indietro: git revert -m 1 <commit di unione> in una nuova richiesta di unione.

Controlli richiesti e protezione di main

I controlli richiesti sono i quattro lavori della verifica, come Gitea li riporta sul commit: verifica / controlli (push), verifica / prove (push), verifica / installatore (push), verifica / immagine (push). Una richiesta di unione mostra lo stato del suo ultimo commit, che il push del ramo ha già verificato: per questo la verifica non gira anche su pull_request.

Regola di protezione di main (Impostazioni ▸ Rami ▸ Aggiungi regola; la imposta chi integra, una volta che i quattro controlli sono comparsi almeno una volta):

Impostazione Valore
Schema del ramo main
Push disattivato: solo da richiesta di unione
Push forzato disattivato
Controllo di stato attivo, con gli schemi verifica / controlli (push), verifica / prove (push), verifica / installatore (push), verifica / immagine (push)
Blocca l'unione se la richiesta è indietro rispetto al ramo di base attivo: con il ramo aggiornato il commit di unione ha lo stesso contenuto del commit verificato
Approvazioni richieste 1 se le richieste le apre un account diverso da quello di Alberto; 0 se le apre lui (Gitea non conta l'approvazione dell'autore)
Annulla le approvazioni superate da nuovi commit attivo
Blocca l'unione con revisioni che chiedono modifiche attivo
Anche gli amministratori seguono la regola attivo

E nei tag protetti (Impostazioni ▸ Tag): v* creabili solo da Alberto.

La CI

Gitea Actions su un solo act_runner (etichetta ubuntu-latest, un lavoro alla volta). I lavori parlano con il demone Docker del server, lo stesso che costruisce Encelado, Mimante e gli altri progetti di Alberto. I flussi stanno in .gitea/workflows/, il codice comune in .gitea/scripts/ (si lancia anche a mano).

Lavoro Quando Che cosa garantisce
controlli ogni push sintassi di tutti gli script di shell (bash -n, sh -n) e righe Unix; flussi senza tabulazioni; nessun segno di conflitto; versione in Directory.Build.props valida; ogni progetto di Febe.slnx esiste; ogni JSON si legge; nessun segreto in tutta la storia (gitleaks 8.30.1, --redact)
prove dopo controlli in un contenitore Debian 13 (node:24-trixie) con Chromium della distribuzione, Xvfb, ffmpeg, NSIS, Node e la lingua italiana: tutta la soluzione compila con gli avvisi come errori e tutte le prove di tests/Febe.Tests passano senza saltarsi; quelle della categoria SitoDiProva passano anche con il seme dell'esecuzione. Risultati .trx fra gli artefatti (14 giorni)
installatore dopo prove Febe.exe in un file solo, Febe-Setup-<versione>-ci.<numero>.exe e lo zip portabile si costruiscono, ciascuno sotto i 100 MB; artefatti per 14 giorni
immagine dopo prove l'immagine si costruisce con buildx (dentro girano compilazione e prove), il contenitore parte senza rete come dice la guida e diventa «healthy», Chromium e la lingua italiana ci sono, si ferma entro 30 secondi; Trivy 0.75.0 non trova vulnerabilità CRITICAL con correzione disponibile. Solo dopo un push su main: pubblicazione :main e :sha-<commit>

La verifica gira a ogni push su qualunque ramo e a mano (Actions ▸ verifica ▸ Esegui, con un seme facoltativo). Su un ramo un push nuovo annulla l'esecuzione in corso; su main ogni unione arriva fino in fondo. Un'esecuzione a mano non annulla mai quella di un push (l'evento fa parte del gruppo di concorrenza): solo il push scrive gli stati del commit che servono per unire, e un lavoro annullato lascerebbe lo stato «failure».

Altri flussi: rilascio.yml a ogni tag (vedi «Rilasci») e pulizia.yml ogni lunedì (vedi «Pulizia»).

Il mondo sintetico e il suo seme

Le prove non contattano mai Instagram: usano il sito di prova (tools/Febe.SitoDiProva), con dati sintetici generati da un seme. Nella CI le prove girano con il seme 13 e quelle della categoria SitoDiProva di nuovo con il seme 1000 + numero dell'esecuzione, scritto nel registro del passo «Semi del mondo sintetico». Per rifare un errore, in locale o dalla CI a mano con quel seme:

FEBE_SEME_PROVA=<seme> dotnet test tests/Febe.Tests --filter "TestCategory=SitoDiProva"

Segreti e variabili

  • REGISTRY_TOKEN (segreto del repository): token di Alberto con «package: read and write». Senza, verifica e rilascio costruiscono, provano e scansionano l'immagine ma non la pubblicano, con un avviso, e restano verdi.
  • REGISTRY (variabile, facoltativa): il registro come lo raggiunge il runner (192.168.30.23:3000); se manca si usa l'host dell'indirizzo del server Gitea.
  • Le credenziali vanno nella configurazione del client Docker del lavoro, mai nel demone, e si tolgono alla fine. Nessun flusso stampa segreti; PipelineTests lo controlla a ogni esecuzione.
  • I segreti sono leggibili da qualunque flusso di questo repository, su qualunque ramo: chi può fare push può leggerli. Per questo il permesso di scrittura sul repository resta ad Alberto e agli account di cui si fida.

Registro dei container: le etichette

Sul registro di Gitea, 192.168.30.23:3000/alby96/febe:

Etichetta Chi la crea Quando cambia Per che cosa
:latest rilascio, solo versioni senza trattino a ogni rilascio stabile Unraid e Docker Compose
:X.Y.Z rilascio (anche X.Y.Z-rc.1 per un'anteprima) mai una versione precisa, per tornare indietro
:main verifica, dopo ogni unione in main a ogni unione (mai all'indietro) provare main su un server di prova; non per l'archivio vero
:sha-<7 caratteri> verifica, dopo ogni unione in main mai un commit preciso di main

Ogni immagine della CI porta le etichette Docker febe.ci.workflow, febe.ci.run, febe.ci.ref e febe.ci.commit, oltre a quelle OCI del Dockerfile: da un'immagine si risale all'esecuzione e al commit. Docker le copia in ogni contenitore creato dall'immagine, anche in un Febe vero: per questo la pulizia non le usa mai per scegliere che cosa togliere (vedi «Pulizia»). Le :sha- si accumulano: una regola di pulizia dei pacchetti (Impostazioni ▸ Pacchetti ▸ Regole di pulizia) può tenere sempre latest, main e le versioni e togliere le sha-.* più vecchie di 30 giorni.

Pulizia

Il demone Docker è condiviso con gli altri progetti, e ci può girare anche un Febe vero, avviato da un'immagine che la CI ha pubblicato e che quindi porta le sue etichette febe.ci.*. La CI di Febe toglie solo ciò che può provare suo (.gitea/scripts/pulizia-docker.sh):

  • contenitori di prova: l'etichetta febe.ci.prova=<esecuzione>, che mette solo prova-immagine.sh con docker run --label e che nessuna immagine porta (lo controlla PipelineTests), e insieme il nome esatto febe-prova-<esecuzione>;
  • immagini provate: il nome locale febe-ci:<esecuzione>, tolto per nome, mai per identificativo e mai con -f. Se la stessa immagine ha anche un nome del registro, quello resta; se un contenitore la usa, resta tutto;
  • builder buildx: il contenitore buildx_buildkit_febe-ci-<esecuzione>0 con l'immagine moby/buildkit e il suo volume …_state;
  • più le immagini senza nome più vecchie di 72 ore che nessun contenitore usa.

PipelineTests fa girare la pulizia contro un demone finto (tests/Febe.Tests/Packaging/fake-docker.sh) con un Febe vero acceso e uno fermo che portano le etichette delle loro immagini: non li deve toccare.

Quando Che cosa si toglie
alla fine di ogni lavoro «immagine», sempre il contenitore di prova con i suoi volumi anonimi, l'immagine provata, il builder buildx dell'esecuzione con la sua cache, l'archivio dell'immagine, le credenziali del registro
all'inizio di ogni lavoro «immagine» i resti di esecuzioni interrotte più vecchi di 90 minuti (un lavoro dura al massimo 60 minuti): contenitori di prova fermi, immagini febe-ci:, builder; e ciò che ha lasciato un tentativo precedente della stessa esecuzione
ogni lunedì e a mano (pulizia.yml) gli stessi resti, l'immagine febe:ci del vecchio flusso se nessuno la usa, le immagini senza nome più vecchie di 72 ore
mai immagini, contenitori e volumi degli altri progetti; un contenitore Febe che non sia di prova, anche se porta le etichette febe.ci.*; un contenitore di prova ancora acceso di un'altra esecuzione (si segnala con un avviso e il comando per toglierlo: il flusso settimanale diventa rosso); la cache di costruzione del demone; i volumi con un nome; le immagini col nome del registro

Rilievi di sicurezza

  • gitleaks (lavoro controlli). Un segreto vero si revoca subito (gettone di Telegram da BotFather, token di Gitea dalle impostazioni dell'utente) e se ne crea uno nuovo: toglierlo dalla storia non basta, perché qualcuno può averlo già. Solo dopo, se serve, si riscrive la storia, d'accordo con Alberto. Un falso allarme (un dato di prova finto, già controllato) si toglie aggiungendo la sua impronta («Fingerprint», nel registro del lavoro o nel rapporto rapporto-gitleaks) a .gitleaksignore, con un commento sulla riga sopra: che cos'è, chi l'ha controllato, quando. Mai disattivare una regola.
  • Trivy (lavoro immagine, anche nel rilascio). Una vulnerabilità CRITICAL con correzione disponibile ferma il lavoro e l'immagine non si pubblica. Che cosa fare: per un pacchetto di Debian di solito basta rilanciare (il Dockerfile applica gli aggiornamenti della distribuzione); per una dipendenza .NET si aggiorna la sua versione in Directory.Packages.props (una dipendenza nuova va chiesta ad Alberto); per il runtime .NET si ricostruisce con l'SDK aggiornato. Le HIGH, e le CRITICAL ancora senza correzione, non fermano nulla ma si guardano nel rapporto sicurezza-immagine (trivy.json) e, se riguardano ciò che Febe usa, diventano una segnalazione. Un'eccezione si scrive solo in .trivyignore, alla radice: l'identificativo con una scadenza (CVE-AAAA-NNNN exp:AAAA-MM-GG, al massimo 90 giorni) e, sulla riga sopra, il motivo e chi l'ha deciso.
  • Strumenti: gitleaks e Trivy sono gli unici strumenti esterni della CI, approvati da Alberto, e girano solo nella CI. Si aggiornano cambiando versione e impronta SHA-256 in .gitea/scripts/strumento.sh, in una richiesta di unione con una riga in docs/decisioni.md, preferendo versioni uscite da almeno due settimane.

Rilasci

  1. In un ramo rilascio/X.Y.Z: <Version> in Directory.Build.props, la sezione ## X.Y.Z di CHANGELOG.md (è il testo delle note della release), docs/stato.md. Richiesta di unione, verifica verde, unione.
  2. Sul commit di unione in main: git tag -a vX.Y.Z -m "Febe X.Y.Z" e git push origin vX.Y.Z.
  3. rilascio.yml controlla che il tag coincida con <Version>, rifà le prove, costruisce installatore e zip, costruisce, prova e scansiona l'immagine, la pubblica come :X.Y.Z (e :latest se la versione non ha trattini) e crea la release con installatore, zip, modello di Unraid e archivio per Compose.
  4. Un'anteprima è vX.Y.Z-rc.N: stessa strada, :latest non si sposta e la release è segnata come anteprima (come ogni versione 0.x).
  5. Se manca REGISTRY_TOKEN la release esce senza immagine e lo dice; aggiunto il segreto, si rilancia il flusso del tag e le note si correggono.

Correzioni urgenti

  • Se main contiene solo ciò che si vuole rilasciare: ramo urgente/<argomento> da main, richiesta di unione con la verifica verde come sempre (nessuna scorciatoia), poi un rilascio di correzione (X.Y.Z+1) come sopra.
  • Se main contiene già lavoro da non rilasciare: ramo rilascio/X.Y dal tag della versione in uso, la correzione con git cherry-pick (o scritta lì), <Version> a X.Y.Z+1, tag vX.Y.Z+1 su quel ramo (il rilascio parte da qualunque tag); poi la stessa correzione entra in main con la sua richiesta di unione.

Che cosa solo la prima esecuzione vera può provare

Qui non ci sono runner né demone Docker: i flussi sono stati controllati come testo (struttura, espressioni, bash -n di ogni blocco run), gli script con un client Docker finto. Restano da vedere alla prima esecuzione: il contenitore node:24-trixie con le azioni dentro; le prove con il browser nel contenitore (nessuna saltata); upload-artifact@v3 con retention-days; la concorrenza; il builder buildx con il nome dell'esecuzione; la prova del contenitore senza rete fino a «healthy»; il download e la scansione di Trivy (e se trova CRITICAL da correggere); gitleaks sulla storia; la pubblicazione su main con il segreto; la pulizia settimanale sul demone vero.