DIEGO CECATO / NOTE DAL CAMPO

NuGet staged publishing: una build riuscita non autorizza una release

diego cecato//
Copertina editoriale sullo staged publishing NuGet e il controllo delle release

La pipeline ha compilato, i test sono verdi, il pacchetto è stato caricato. In molti progetti, a questo punto, la versione è già pubblica. Il problema non è l’automazione: è averle consegnato anche l’ultima decisione, quella che rende un artefatto disponibile a migliaia di applicazioni. Dal 17 novembre 2026 NuGet.org offre una separazione esplicita tra preparare una release e autorizzarne la distribuzione. È un cambiamento piccolo nell’interfaccia e piuttosto importante nella responsabilità.

Lo staged publishing annunciato dal team .NET è facoltativo e disponibile ai publisher NuGet.org. I normali workflow con dotnet nuget push continuano a funzionare: non è un obbligo di migrazione. La domanda utile è un’altra: quali passaggi devono restare automatici e quale decisione non dovrebbe essere implicitamente delegata alla CI?

Tre controlli diversi che spesso chiamiamo tutti “release”

Una build riuscita dimostra che il processo di compilazione è terminato secondo i criteri configurati. I test verificano le condizioni che abbiamo scritto, non tutte quelle che avremmo dovuto scrivere. La validazione del registry controlla un altro insieme di proprietà. Nessuno di questi passaggi prova da solo che il pacchetto, quella versione e quel momento siano quelli giusti per pubblicare.

Con lo staging, NuGet.org riceve il pacchetto e lo sottopone alla propria pipeline di convalida, che comprende controlli malware, firme e repository signing. L’artefatto rimane però fuori dalle pagine pubbliche, dalla ricerca e dalle operazioni di restore. Solo un maintainer autorizzato lo promuove dal sito. Il confine è concreto: una pipeline può preparare un candidato senza renderlo immediatamente una dipendenza pubblica.

Una release non è semplicemente il risultato di una build. È una decisione sulla versione, sulle dipendenze e sul momento in cui altri sistemi potranno consumarla.

Un token che può caricare non dovrebbe poter pubblicare

La separazione funziona davvero quando riguarda anche le credenziali. Una chiave API limitata allo staging può caricare pacchetti per la revisione ma non usare il normale percorso di push per pubblicarli direttamente. Se una pipeline viene compromessa, questo limita una parte del danno possibile: l’attaccante può proporre un artefatto, non distribuirlo automaticamente tramite quella credenziale. Non significa che il pacchetto sia affidabile, né che l’account del maintainer sia al sicuro.

Microsoft consiglia di combinare questa scelta con NuGet Trusted Publishing, basato su identità OIDC e credenziali temporanee. Sono due difese differenti: la credenziale a vita breve riduce l’esposizione dei segreti; il permesso staging-only limita ciò che l’automazione può fare; l’approvazione umana governa la pubblicazione. Nessuna delle tre sostituisce le altre.

La promozione avviene su NuGet.org con un utente autorizzato e autenticazione a due fattori abilitata. Questo non equivale a dire che ogni click richieda una nuova challenge 2FA: sarebbe una promessa di sicurezza non documentata. Conta il controllo effettivo sul passaggio di stato, non una formula rassicurante.

Cinque pacchetti, un gruppo, nessuna transazione atomica

Per librerie, analyzer e integrazioni che devono uscire insieme, NuGet.org permette di raccogliere più artefatti in uno staging group. Il maintainer può vedere lo stato di convalida dell’insieme e avviare una promozione di gruppo. Ma un unico comando di approvazione non produce un commit distribuito atomico: i pacchetti attraversano la pubblicazione indipendentemente e possono diventare ripristinabili in momenti differenti.

È il dettaglio più facile da perdere in una demo. Se il pacchetto B richiede una nuova versione di A, durante la finestra di propagazione potrebbe non esserci ancora l’intero insieme disponibile. Occorre progettare dipendenze e compatibilità tenendo conto di questa finestra, verificare gli esiti per singolo pacchetto e coordinare gli annunci soltanto dopo aver osservato la disponibilità reale. Il gruppo aiuta a governare la release, non promette una transazione che il registry non offre.

Staged non significa unlisted, e non è un feed di test

Un pacchetto unlisted resta installabile conoscendo ID e versione. Uno staged, invece, non è disponibile al restore neppure per il proprietario. Di conseguenza lo staging non è un sostituto di un feed privato su cui eseguire test end-to-end. I test di installazione, risoluzione delle dipendenze e compatibilità devono avvenire prima, su feed locali o privati; lo staging serve a preparare e convalidare gli artefatti finali presso NuGet.org.

Anche la durata va gestita: gli artefatti staged non restano conservati per sempre e possono scadere se non vengono promossi. Per release coordinate con date precise serve controllare le notifiche di scadenza e non considerare lo staging un archivio permanente.

Che cosa può fare oggi la CLI

Con .NET 11 RC2 è documentato l’upload in staging tramite dotnet package stage push, con l’opzione --group per associare un pacchetto a un gruppo. L’upload accettato non significa convalida completata né pubblicazione avvenuta. La gestione e l’elenco dei gruppi da CLI sono presentati da Microsoft come funzionalità future: non vanno inseriti in una pipeline di produzione come se fossero già disponibili. La promozione resta un’azione sul sito NuGet.org.

Questa scelta impedisce, almeno nel percorso descritto al lancio, che una stessa sequenza automatizzata completi inavvertitamente preparazione e pubblicazione. È un compromesso deliberato: meno automazione nell’ultimo metro, più controllo su ciò che finisce nel registry.

Una checklist utile prima di premere Promote

  • Verificare ID, versione, proprietario e hash degli artefatti rispetto al piano di release.
  • Controllare che ogni pacchetto del gruppo abbia superato la convalida e che non manchino dipendenze.
  • Accertarsi che la CI abbia solo le autorizzazioni necessarie e che i maintainer abbiano accessi protetti.
  • Valutare la compatibilità durante la finestra di distribuzione non atomica e predisporre monitoraggio per ogni pacchetto.
  • Dopo la promozione, verificare il restore reale delle versioni pubblicate prima di annunciare che la release è completa.

Il punto non è aggiungere un click

Un’approvazione manuale senza informazioni è solo un altro pulsante da premere. Il valore nasce quando chi approva può confrontare gli artefatti con un piano, capire le dipendenze, vedere le validazioni e assumersi una decisione informata. È lo stesso principio che dovrebbe valere per un deploy applicativo, una migrazione database o un aggiornamento infrastrutturale: automatizzare la preparazione non obbliga ad automatizzare l’autorizzazione.

In un precedente approfondimento su NuGet e istruzioni per agenti il problema era distinguere il contenuto distribuito dall’autorità che gli attribuiamo. Qui il confine è diverso ma la lezione operativa è affine: il registry può validare e distribuire un artefatto; la responsabilità di decidere se e quando rilasciarlo resta a chi governa il sistema.

Domande frequenti

Che differenza c'è tra staged e unlisted su NuGet.org?

Un pacchetto staged non è disponibile al restore e resta privato fino alla promozione. Un pacchetto unlisted può ancora essere ripristinato conoscendone ID e versione.

La promozione di uno staging group pubblica tutti i pacchetti nello stesso istante?

No. La promozione del gruppo non è atomica: i singoli pacchetti possono diventare disponibili in momenti diversi, quindi vanno verificati separatamente.

Posso testare un pacchetto staged installandolo da NuGet.org?

No. Lo staging non offre un feed privato di restore, neppure al proprietario. I test di installazione vanno eseguiti prima su un feed locale o privato.

Lo staged publishing sostituisce NuGet Trusted Publishing?

No. Trusted Publishing riduce l’uso di segreti persistenti tramite credenziali temporanee OIDC; lo staging separa il caricamento dalla decisione di rendere pubblica la release.

Serve una nuova verifica 2FA a ogni promozione?

La promozione richiede un utente autorizzato con 2FA abilitata, ma Microsoft non garantisce una nuova challenge a ogni singola promozione.