Pre-deploy checklist: cosa controllare prima di pubblicare

Pre-deploy checklist non è burocrazia: è il filtro che intercetta gli errori più banali e dannosi. Build rotta, segreto committato, console.log in produzione, env mancanti. Cinque minuti di check sistematico evitano incidenti di ore. La checklist deve esistere PRIMA del primo deploy, non dopo il primo incidente.

Perché questa lezione conta

I bug che fanno più male al deploy non sono sofisticati. Sono ovvi: la pagina mostra “TODO”, la chiave API è in chiaro, il banner cookie non c’è, i link puntano a localhost. Senza checklist, sai che dovresti controllare ma dimentichi. Con checklist, ogni deploy passa attraverso lo stesso filtro. Predicibilità > eroismo.

Obiettivo operativo

Alla fine devi saper:

1. eseguire una pre-deploy checklist completa in 5-10 minuti;
2. distinguere voci “blocking” (rimanda deploy) da “consigliate” (fix dopo);
3. integrare check automatici dove possibile, manuali dove necessario.

Nucleo della lezione

1. Categorie di check

Sei aree, ognuna con voci specifiche:

Build e codice:

• build pulita (no warning, no error);
• typecheck verde;
• linter senza errori (warning ok ma annotare);
• test passano (unit + integration);
• nessun console.log/debugger non voluto;
• nessun TODO/FIXME su feature critica.

Configurazione:

• env produzione presenti e corretti;
• env non committati in repo;
• URL/endpoint puntano a produzione (non localhost);
• feature flag in stato corretto;
• CORS configurato (non *).

Sicurezza minima:

• nessun segreto nel bundle client;
• security headers (HSTS, CSP base, X-Frame-Options);
• HTTPS forzato (redirect HTTP);
• rate limiting su endpoint sensibili (login);
• error messages generici per esterno.

Dati:

• demo/seed data rimossi se non destinati a produzione;
• backup attivo e testato;
• migrazioni applicate;
• niente PII di persone reali nel DB.

UX essenziale:

• stati vuoti presenti;
• loading state visibile;
• error state azionabile;
• mobile responsive funzionante;
• navigazione tastiera completa;
• pagina 404 personalizzata.

Osservabilità:

• log utili (errori, eventi rilevanti);
• monitoring base (uptime check);
• procedura rollback documentata;
• alerting su errori critici.

2. Automatizzato vs manuale

Più check automatizzato, meno errore umano. Pipeline CI ideale:

Bloccanti automatici (CI step):

• linter
• typecheck
• test (unit + integration)
• build
• audit dipendenze (npm audit --audit-level=high)
• gitleaks (anti segreti)

Bloccanti manuali (pre-merge review):

• review codice
• check sicurezza (vedi lezione 57)
• check accessibilità
• test manuale dei flussi principali

Consigliati (warning, non bloccanti):

• coverage minima
• bundle size
• Lighthouse score

CI deve fallire se uno dei bloccanti automatici fallisce. Niente merge a main con CI rosso.

3. Procedura di rollback

Cosa fai se il deploy va male:

Rollback piattaforma: Vercel, Netlify, Fly hanno “rollback” a versione precedente in 1 click. Usalo come prima azione.

Rollback codice: git revert del commit problematico, deploy del nuovo HEAD.

Rollback DB: se la migrazione è il problema, esegui migrazione down. Se non reversibile, restore da backup (più lento, ultima risorsa).

Documenta: ogni rollback va loggato con motivo, downtime, lezione appresa. Diventa post-mortem leggero (vedi lezione 59).

Pre-condizione: rollback va testato almeno una volta, non al primo incidente.

Caso guidato

App pronta per demo pubblica: form contatti con invio email. Checklist minima prima del deploy:

Build:
□ npm run build passa
□ nessun errore console nel flusso principale

Env:
□ API key email presente solo nel pannello hosting
□ `.env` non committato
□ `.env.example` contiene solo nomi variabili

UX:
□ stato loading durante invio
□ errore se rete assente
□ messaggio successo chiaro
□ form usabile da tastiera

Sicurezza:
□ validazione lato server
□ rate limit o protezione spam minima
□ messaggio errore non espone stack trace

Rollback:
□ so tornare al deploy precedente
□ ultimo commit funzionante identificato

Se una voce critica fallisce, non “pubblicare e sistemare dopo”. Esempio: API key nel bundle client. Non è un dettaglio estetico: va corretta prima, chiave ruotata, cronologia controllata. La checklist serve proprio a distinguere blocchi veri da piccole rifiniture.

A fine controllo scrivi sempre una nota di rilascio minima: cosa è stato verificato, cosa resta escluso, come tornare indietro. Una demo senza note sembra più veloce, ma quando qualcosa va male nessuno ricorda più quali controlli erano stati fatti.

Procedura pratica

Pre-deploy in 10 minuti:

1. Build locale pulita: npm run build senza errori/warning nuovi.
2. Test green: npm test tutto verde.
3. git status: niente file non commit, branch in main.
4. Diff vs main precedente: git diff main~1. Niente di sorprendente.
5. Cerca pattern sospetti: grep -r 'console.log\|TODO\|FIXME\|localhost\|api_key\s*=' src/.
6. Env verification: pannello hosting ha tutte le env attese.
7. Smoke local: app parte localmente con env produzione (in modalità sicura).
8. Deploy: push o trigger.
9. Smoke produzione: dopo deploy, verifica che app risponda + 1-2 endpoint chiave + 1 pagina principale.
10. Monitoring: check log/dashboard per errori nei primi 5 minuti.

Se uno step fallisce, fermati. Non saltare a “deployo lo stesso, sistemiamo dopo”.

Laboratorio guidato

Crea checklist file docs/pre-deploy.md per il tuo progetto:

# Pre-Deploy Checklist

## Codice
- [ ] `npm run build` pulita (no warning nuovi)
- [ ] `npm test` tutto verde
- [ ] `npm run lint` no errori
- [ ] `npm run typecheck` no errori
- [ ] No `console.log` orfani: `grep -r "console.log" src/`
- [ ] No TODO/FIXME su feature critica

## Config
- [ ] env produzione complete (lista nel pannello)
- [ ] `.env` NON in repo (`git status` pulito)
- [ ] URL puntano a produzione (no localhost)
- [ ] CORS specifico (non `*`)

## Sicurezza
- [ ] `npm audit` no high/critical
- [ ] Nessun segreto nel bundle (`grep` build output)
- [ ] HSTS + CSP + X-Frame-Options
- [ ] HTTPS forzato
- [ ] Rate limit su /login, /signup
- [ ] Error 500 generici (no stack trace)

## Dati
- [ ] Backup attivo (verifica pannello DB)
- [ ] Migrations applicate (`drizzle-kit migrate` o equivalente)
- [ ] No PII reale in DB
- [ ] Seed/demo data rimosso

## UX
- [ ] Stati vuoti presenti su liste
- [ ] Loading state visibile
- [ ] Error state azionabile
- [ ] Mobile responsive (Chrome devtools mobile)
- [ ] Navigazione tastiera (Tab attraverso flussi principali)
- [ ] Pagina 404 personalizzata

## Osservabilità
- [ ] Log strutturati (no console.log random)
- [ ] Errori in Sentry/equivalente
- [ ] Uptime check (BetterUptime, Cronitor, ecc.)
- [ ] Alerting su 5xx ratio

## Post-deploy (entro 5 min)
- [ ] Smoke test produzione: 3 endpoint chiave
- [ ] Check log: nessun errore nuovo
- [ ] Check dashboard: traffico normale

Esegui la prima volta su deploy reale. Aggiungi/togli voci man mano.

Output atteso

Documento docs/pre-deploy.md per il tuo progetto, eseguibile in 10 minuti. Storico di ultimi N deploy con timestamp e responsabile (utile in caso di incidente).

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: costruire un rito finale di verifica che intercetti errori banali ma pericolosi prima del rilascio. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Build pulita, test eseguiti, console senza errori, env corretti, dati demo rimossi, segreti non committati.
• UX essenziale: stati vuoti, loading, errori, mobile, navigazione tastiera, pagine 404 o fallback.
• Osservabilità minima: log utili, messaggi di errore non sensibili, monitoraggio base, procedura di rollback.

3. Applicazione: svolgi il laboratorio: applicare la checklist a un prototipo e bloccare il deploy finché le voci critiche non sono risolte. L’output da ottenere è: una checklist pre-deploy riutilizzabile per progetti personali, clienti o demo pubbliche.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho una pre-deploy checklist scritta;
• l’ho eseguita per l’ultimo deploy;
• ho automatizzato almeno gli step bloccanti (CI);
• so come fare rollback;
• post-deploy verifico smoke + monitoring per 5 minuti.

Errori comuni

Niente checklist. Ogni deploy è artigianale. Errori imprevedibili.

Checklist troppo lunga. 50 voci → la salti. 15-20 voci essenziali, automatizza il resto.

Skip in fretta. “Tanto è urgent”. Errori urgenti sono peggiori di errori non urgenti.

Niente smoke post-deploy. Deploy “successo” del CI ≠ app funzionante. Verifica dal vivo.

Niente monitoring post-deploy. Errori nei primi 5 minuti scoperti dagli utenti, non da te.

Niente piano rollback. Vai in panic mode al primo problema.

CI rosso ignorato. “Fallisce sempre, ignora”. Non fixi root cause, accumuli debito.

Prompt di lavoro

Aiutami a costruire pre-deploy checklist per la mia app: [descrizione]

Stack: [...]
Hosting: [Vercel, Netlify, Fly, ...]
DB: [...]
Auth: [...]

Voglio:

1. Checklist organizzata in 6 categorie (codice, config, sicurezza, dati, UX, osservabilità).
2. Per ogni voce: comando concreto da eseguire (no descrizioni vaghe).
3. Distinzione bloccante / consigliato / nit.
4. Quali voci automatizzare in CI vs eseguire manualmente.
5. Procedura di rollback specifica per la mia piattaforma di hosting.
6. 5 voci di smoke test post-deploy.

Output: file markdown pronto da copiare in docs/pre-deploy.md, max 30 voci totali.

NON includere voci ovvie generiche ("scrivi codice corretto"). Solo cose verificabili e specifiche.

Esercizio finale

Per il prossimo deploy del tuo progetto, esegui la checklist anche se ti sembra superfluo. Misura: tempo speso (target < 10 min), voci che hanno bloccato il deploy (target 1-3, sintomo che la checklist funziona). Se zero voci bloccano mai, la checklist è troppo permissiva o il tuo workflow è già perfetto (raro).