## Definizione del problema Un recente incident (guasto silenzioso su più workflow di integrazione, causato da un upgrade di Windmill) ha messo in luce che gli upgrade della piattaforma di orchestrazione non vengono validati eseguendo i workflow prima del rilascio in produzione. Nel caso specifico: l'ambiente QA era stato aggiornato alla stessa versione **7 giorni prima** della produzione, ma nessun workflow di integrazione vi è stato eseguito in quella finestra. Il guasto (introdotto dal cambio di runtime Python conseguente all'upgrade) è quindi rimasto invisibile 7 giorni in QA e altri 6 in produzione: l'ambiente di collaudo esisteva, ma non è stato usato per collaudare. Il tema di fondo: un upgrade di Windmill non è l'aggiornamento di un'applicazione che ospita codice inerte, è un **upgrade del runtime di tutti i workflow** (interprete, risoluzione dipendenze, versione della CLI di sync, comportamento delle API, gestione worker/code). Serve quindi un percorso di collaudo dedicato a questa superficie, distinto da un generico smoke test applicativo. Dettaglio completo dell'incident: [documento di analisi](https://docs.google.com/document/d/1dAwZ1jnaZYJEXFHb-MgJ_m49ZOIWU1LikQ-sMHSoNlI/edit) (Fase 7 - Lezioni apprese, sezione "Prima dell'upgrade"). ## Possibili soluzioni 1. **Collaudo manuale post-aggiornamento QA**: prima di rilasciare in produzione, eseguire almeno un'esecuzione per ciascun workflow critico su QA e verificarne i contatori di esito (non lo stato del job, che risulta `success` anche col difetto presente). 2. **Collaudo automatizzato/schedulato su QA**: uno smoke test periodico che esegue i workflow critici e confronta i contatori di business con una baseline nota (es. "chiamate AI riuscite \> 0 se sono stati creati atti"). 3. **Integrare il collaudo nella production readiness esistente**: tenere la modalità di collaudo vicina al processo di production readiness già in uso nel repo, invece di introdurre un processo parallelo — vedi template `production-readyness.md`. Da decidere anche: chi esegue il collaudo, con quale periodicità (ogni upgrade minor o solo su salti di versione ampi), e come si lega alla finestra QA→produzione (nel caso recente 7 giorni, più che sufficienti se effettivamente usati). ## Esito della discussion Deciso in riunione del 15/09/2026 (dettaglio nel commento di sintesi qui sotto). **Opzione scelta**: una variante delle opzioni 2 e 3, adattata al contesto Windmill. - Il collaudo automatizzato non è uno smoke test periodico schedulato su QA (opzione 2 pura), ma un ambiente di test Windmill dentro la **CI di GitLab**, eseguito ad ogni upgrade partendo dal codice del repository. - Non si integra nella Production Readiness esistente (opzione 3) perché quel processo (scansioni Docker, test API) è pensato per microservizi e non si adatta all'architettura serverless/workflow di Windmill. **Perché non il collaudo manuale (opzione 1)**: un collaudo manuale periodico di tutti i flussi ad ogni upgrade richiede un carico di lavoro insostenibile per il team ed espone al rischio di essere saltato — come accaduto nell'incident che ha originato questa discussion. **Decisioni operative**: 1. Predisporre un ambiente di test Windmill nella CI di GitLab: ad ogni upgrade si eseguono tutti i flow critici di un workspace, come primo gate prima del deploy in QA e produzione. 2. Usare le metriche operative di Windmill (critical alerts, errori nelle runs) come segnale di rottura post-upgrade — non lo stato del job, che può risultare `success` anche col difetto presente. 3. Mantenere il pinning rigido di dipendenze e versione dell'interprete Python (header script + file di lock), per garantire coerenza tra ambiente dichiarato ed eseguito. 4. Il monitoraggio degli alert/metriche di ciascun workspace è responsabilità continuativa di chi lo gestisce, e non un passaggio aggiuntivo nella procedura di upgrade: l'upgrade non deve essere il momento in cui si scopre un alert pendente da tempo. In fase post-upgrade, il Team Ops verifica sistematicamente i critical alerts e le run fallite per individuare eventuali anomalie introdotte dall'upgrade stesso. 5. Allineare la versione di `windmill-cli` usata dalla pipeline CI per il sync, oggi disallineata tra i due branch di ambiente (a carico del Team Ops). Questo percorso è complementare, non alternativo, all'alerting Prometheus sulle metriche di business già proposto: il collaudo in CI intercetta il guasto _prima_ del rilascio, l'alerting lo intercetta _dopo_, se il collaudo viene saltato o non copre il caso. ## Scelte tecnologiche e architetturali Il collaudo è complementare, non alternativo, all'alerting sulle metriche di business già proposto (regole Prometheus su contatori pubblicati dai flow) e a un eventuale dead man's switch: il primo intercetta il guasto _prima_ del rilascio, il secondo lo intercetta _dopo_, se il collaudo viene saltato o non copre il caso. Da valutare se includere nel collaudo anche il controllo di allineamento della CLI (`windmill-cli`) usata dalla pipeline CI per il sync, oggi disallineata tra i due branch di ambiente. ## Observability Il collaudo deve produrre un segnale verificabile e confrontabile con una baseline nota — contatori di esito del workflow, non stato del job — coerentemente con i Four Golden Signals (in particolare error rate applicativo). ## UX n/a — processo interno, non user-facing. ## Scalabilità Il percorso deve restare sostenibile al crescere del numero di integrazioni che dipendono in modo sensibile dal runtime fornito da Windmill. ## Impatti sicurezza n/a ## Manutenibilità Un percorso di collaudo formalizzato riduce il rischio che un futuro upgrade riproduca lo stesso schema (fallback silenzioso + nessun collaudo + nessun alert = guasto invisibile per giorni). ## Delivery Da legare al formato minimo di annuncio upgrade proposto in Fase 7 ("Durante l'upgrade": versione da→a, changelog, issue, impatto, referente), così che il collaudo abbia un trigger esplicito e tracciabile. ## Roadmap - Rilascio in Fast track: - Rilascio in Scheduled track: