Principi
- Un solo ambiente di produzione, mai un bundle non osservato. Ogni modifica attraversa una replica (staging) o una preview a traffico zero della produzione stessa, prima che un utente la veda.
- Il gate è umano e tracciato. Nessun rilascio in produzione
senza approvazione esplicita del gestore, registrata su GitHub
(environment
productioncon required reviewer). - Rollback in secondi, senza rebuild. Cloudflare Workers
conserva le versioni precedenti:
wrangler rollbackriporta indietro immediatamente. - Lo staging non contiene mai dati reali. I database di staging nascono dagli schemi versionati nel repo più dati sintetici: copiare dati di produzione sarebbe un trattamento GDPR senza scopo.
- I segreti di produzione non lasciano il loro perimetro. Lo staging ha segreti propri, generati apposta. In particolare il segreto che firma le attestazioni — non ruotabile per progetto — esiste solo in produzione e nel caveau di escrow.
- Il config non può divergere. Produzione e staging vivono
nello stesso file di configurazione (
wrangler.toml, blocco[env.staging]): ogni modifica tocca entrambi nello stesso commit, il drift è strutturalmente impossibile.
Lo stesso processo — staging replicato, CI, gate umano, rollback in secondi — è adottato anche per gli altri servizi dell'ente.
Le parti: produzione e replica
Mappa dettagliata
| Componente | Produzione | Staging |
|---|---|---|
| imgauth (motore) | Worker imgauth · imgauth.spaziogenesi.org | imgauth-staging · solo workers.dev |
| Database / archivio | imgauth-health · imgauth-pdf-archive (EU) | gemelli -staging, senza dati reali |
| Firma PDF (authart) | Azure, marca temporale TSA | non replicata in v1: PDF non firmato |
| Anti-bot / notifiche | Turnstile reale · Telegram | chiavi di test · silenzioso |
| authweb (interfaccia) | GitHub Pages · attestazione.spaziogenesi.org | copia generata dal medesimo sorgente, puntata allo staging |
Flusso di rilascio
Runbook
Rilascio ordinario
- PR con la modifica → i check devono essere verdi.
- Merge su
main→ lo staging si aggiorna da solo; controllare lo smoke. - Prova manuale su staging se la modifica è UI/flusso.
- Approvare il job
productionsu GitHub → preview a 0% → promozione. - Smoke di produzione:
/ping(versione attesa),/api/statustutto verde. - Tag
vX.Y.Zse c'è bump di versione; documentazione secondo convenzione.
Hotfix urgente
Identico al rilascio ordinario — la catena È la via veloce (staging automatico + un click di approvazione). Saltare lo staging non è previsto: se la produzione è già rotta, il rollback è più rapido di qualunque fix scritto di fretta.
Rollback
npx wrangler rollback # scegliere la versione precedente
Poi: smoke di produzione, nota su cosa è andato storto, fix con calma attraverso la catena normale.
Aggiungere lo staging a un modulo nuovo
- Creare D1/R2
-stagingdel modulo (EU dove pertinente). - Blocco
[env.staging]nelwrangler.toml: ridichiarare tutti i binding (gli env di wrangler non ereditano dal top-level). - Schemi applicati alla D1 staging, secret nuovi con
--env staging. - Smoke, poi CI come da modello (il workflow di imgauth è il riferimento).
Limiti dichiarati
Onestà del processo: cosa la replica non copre, per scelta documentata.
- La firma PDF non ha replica in v1: lo staging emette PDF non firmati, identici nel contenuto. La replica del firmatario è rinviata alla prossima modifica sostanziale di quel componente.
- Il flusso OAuth self-service non è attivo in staging: i provider richiederebbero redirect URI dedicati; i bottoni restano assenti per design fail-closed.
- La promozione v1 è 0% → 100% dopo approvazione; il rollout percentuale graduale è un raffinamento successivo.
Stato di attuazione
| Fase | Contenuto | Stato |
|---|---|---|
| 0 | Inventario e prerequisiti | ✅ 2026-07-11 |
| 1 | Codice del motore pronto al multi-ambiente | ✅ 2026-07-11 |
| 2 | Staging del motore di attestazione | ✅ 2026-07-11 |
| 3 | CI (check su PR, staging automatico + smoke) | ✅ 2026-07-11 |
| 4 | Gate di produzione (approvazione, preview 0%, rollback provato) | ✅ 2026-07-11 |
| 7 | Interfaccia web di staging | ✅ 2026-07-11 |
| 8 | Pubblicazione della documentazione + registrazione nel GTF | ✅ 2026-07-11 |
La tabella viene aggiornata alla chiusura di ogni fase (data + esito). Il
processo è registrato nel registro GTF come decisione, processo e
controllo (ADR-P24 CTL-cicd-pipeline,
status: active dal 2026-07-11) con evidenza verificabile: i
run di CI sono pubblici sui repo GitHub — chiunque può controllare che il
processo dichiarato sia quello praticato. Le fasi 5 e 6 del piano P24
riguardano un altro progetto e non fanno parte di questo percorso.