Vai al contenuto

Deployment standard in produzione

Quando usarlo

Per promuovere il normale delivery revisionato di D1, API ed Editorial MCP in Production quando Fra esprime esplicitamente l'intento Production.

Il percorso standard è destinato a release Worker reversibili e a migration D1 ordinarie append-only. Operazioni con rischio o scope materialmente distinto restano fuori da questo runbook.

Prerequisiti

Servono:

  • delivery scope già revisionato;
  • current main come candidate;
  • CI verde sul candidate;
  • release Development verde sullo stesso candidate;
  • Environment Production disponibile;
  • credenziali Cloudflare disponibili al job protetto;
  • assenza di una release Production concorrente.

Fra esprime l'intento:

Rilascia in production.

Non serve una seconda Issue operativa quando il percorso è soltanto il normale release Worker reversibile. Questo vale anche per il recupero di un bug Production confermato che non aggiunge operazioni o rischio distinti.

Procedura

  1. Avviare production-release.yml tramite workflow_dispatch su main.
  2. Il workflow congela autonomamente il candidate.
  3. Verificare candidate main, CI verde e Development verde sullo stesso commit prima di entrare nell'Environment protetto.
  4. Applicare le migration D1 pending tramite Wrangler nativo.
  5. Se l'apply fallisce, eseguire una sola riconciliazione autorevole del ledger; continuare solo se lo stato è convergente.
  6. Deployare API tramite la configurazione canonica wrangler.jsonc.
  7. Eseguire smoke API/D1.
  8. Deployare Editorial MCP tramite apps/mcp/wrangler.jsonc.
  9. Eseguire smoke MCP.
  10. Osservare il run fino allo stato terminale e conservare il summary sanitizzato.

L'ordine standard è:

candidate
→ CI
→ Development
→ D1
→ API
→ smoke API
→ MCP
→ smoke MCP
→ terminal

Il normale percorso non richiede tag SemVer, previous Production release, Worker-version upload/reuse state o temporary release projection.

D1

Le migration repository sono append-only.

Il normale apply usa wrangler d1 migrations apply.

Un apply riuscito continua immediatamente. Un apply fallito permette un solo authoritative ledger readback. Stato pending o unknown blocca il release; non esistono retry ciechi.

Una migration o data operation straordinaria o distruttiva richiede scope operativo separato.

Configurazione Worker

wrangler.jsonc è l'unica configurazione repository-side deployable dell'API Worker.

apps/mcp/wrangler.jsonc è l'unica configurazione repository-side deployable dell'Editorial MCP Worker.

Il normale Production deploy usa Wrangler direttamente con:

--env production --keep-vars

Non esistono binding whitelist o projection release-specific da aggiornare in parallelo.

Verifiche attese

Devono risultare coerenti e verdi:

  • candidate Production congelato dal workflow;
  • appartenenza del candidate alla history di main;
  • CI verde sullo stesso commit;
  • release Development verde sullo stesso commit;
  • esito D1 success oppure reconciled-after-failure con stato convergente;
  • deploy API riuscito;
  • smoke API/D1 riuscito;
  • deploy MCP riuscito;
  • smoke MCP riuscito;
  • summary terminale sanitizzato.

Il deployment MCP prova lo stato del server. Un client ChatGPT, Codex o plugin può continuare a mostrare un catalogo tool cached; il refresh del client è separato dal Worker deployment.

Condizioni di stop

Fermarsi quando si verifica una delle seguenti condizioni:

  • candidate non valido o non appartenente a main;
  • CI non verde sul candidate;
  • evidenza Development mancante o non verde sullo stesso commit;
  • release Production concorrente;
  • credenziali Cloudflare mancanti;
  • D1 apply fallito e reconciliation non convergente;
  • ledger D1 pending, ahead, reordered, duplicato o ambiguo;
  • stato runtime ambiguo senza readback autorevole;
  • scope che introduce un'operazione materialmente distinta o ad alto impatto.

Queue topology/configuration, Access/security, operazioni distruttive, external-provider mutation e Mailjet side effect non sono autorizzati da questo runbook.

Non eseguire retry ciechi dopo un esito ambiguo.

Rollback o recupero

Una normale recovery Worker usa un candidate repository known-good già revisionato e lo ridistribuisce attraverso lo stesso percorso Wrangler canonico dopo aver stabilito lo stato corrente.

La recovery Worker non riattiva previous version ID né dipende da uno storico custom di upload.

D1 recovery è separata dalla Worker recovery. Non modificare, rinominare, riordinare o riscrivere una migration già applicata.

Se il recupero richiede extraordinary D1/data migration, Access/security, Queue topology/configuration, azione distruttiva, external-provider mutation o altro scope materialmente distinto, fermarsi e usare una Issue operativa separata e revisionata.

Evidenza da conservare

Conservare soltanto evidenza sanitizzata:

  • Issue e merge che definiscono il delivery scope;
  • candidate/commit congelato;
  • run CI;
  • run Development sullo stesso commit;
  • run Production;
  • esito D1 apply e reconciliation;
  • esito deploy API;
  • esito smoke API/D1;
  • esito deploy MCP;
  • esito smoke MCP;
  • risultato terminale del workflow.

Non registrare secret, credenziali, valori runtime operator-managed, recipient data, provider payload privati o altra evidenza Production sensibile.

Il workflow summary è l'evidenza primaria.