Token stage-only di npm: quali prove conservare quando si separano automazione del deployment e approvazione finale
Separare il permesso della CI di creare un pacchetto da quello di pubblicarlo per gli utenti rende più chiara la responsabilità finale del rilascio. Tuttavia, aggiungere semplicemente un pulsante di approvazione non elimina i rischi per la supply chain. È necessario innanzitutto stabilire cosa deve verificare l'approvatore.
Il 18 settembre GitHub ha annunciato che nei token di accesso granulari (granular access tokens) di npm è possibile selezionare l'autorizzazione di scrittura stage-only. Il flusso prevede che l'automazione invii una versione in attesa di revisione e che il manutentore ne approvi la pubblicazione tramite 2FA. Di seguito vengono distinti i cambiamenti ufficiali dalle proposte operative della redazione per implementarli.
Bloccare la pubblicazione diretta è diverso dal rimuovere i permessi di scrittura
Secondo la documentazione ufficiale, questo token consente di eseguire npm stage publish, ma la pubblicazione diretta tramite npm publish viene rifiutata. Questa limitazione si applica anche in presenza di impostazioni di bypass 2FA per l'automazione. Non si tratta di una modifica automatica del comportamento dei token esistenti, bensì di un'opzione da adottare volontariamente.
Un aspetto importante da considerare è che rimangono altri permessi di scrittura sul pacchetto, come lo spostamento dei dist-tag e la deprecation delle versioni. Il nome stage-only non deve essere interpretato come un token di sola lettura o del tutto innocuo. È ancora necessario gestire l'ambito dei pacchetti consentiti, la posizione di archiviazione dei secret, i soggetti autorizzati e le procedure di revoca.
Definire il pacchetto di rilascio che l'approvatore deve confrontare
Quanto segue non costituisce una configurazione obbligatoria di npm, ma una proposta operativa per team di piccole dimensioni. Includete in ogni richiesta di approvazione il commit del codice sorgente, il pacchetto di destinazione e la relativa versione, i risultati dei test, l'elenco dei file inclusi nel pacchetto e un riepilogo delle modifiche. Se l'approvatore deve raccogliere le prove consultando diversi log di CI, la revisione rischia di ridursi a un clic formale.
In particolare, la revisione del codice sorgente e la revisione dei file di distribuzione sono due cose distinte. Durante il processo di compilazione potrebbero essere inclusi file non presenti nel repository o, al contrario, potrebbero mancare file necessari. Il team può stabilire come principio di preparare il materiale di revisione sulla base degli artefatti effettivamente inviati e di considerare l'artefatto come oggetto di una nuova revisione qualora venga modificato dopo la verifica.
C'è uno stato di attesa anche dopo una CI con esito positivo
Se la precedente automazione segnalava il successo del comando come completamento del rilascio, è necessario innanzitutto modificare la rappresentazione dello stato. Si possono distinguere l'invio completato, l'attesa di approvazione e la pubblicazione completata, registrando per ciascuno le relative conferme. Nelle notifiche, indicare la fase corrente e la persona responsabile è molto più utile per gli operatori rispetto a una semplice dicitura di «successo».
A titolo di esempio ipotetico, se una CI notturna invia una nuova versione ma il responsabile la esamina solo il giorno seguente, non si dovrebbero inviare annunci di rilascio agli utenti al momento dell'invio. È preferibile sincronizzare la documentazione o le notifiche solo dopo la conferma della pubblicazione stabilita dal team. Occorre anche concordare in anticipo chi deve revisionare quando la coda si accumula e quando eliminare i precedenti invii.
Verificare la migrazione su un singolo pacchetto a basso impatto
Attualmente, i prerequisiti indicati nella guida ufficiale includono un pacchetto npm esistente, i permessi di pubblicazione del pacchetto, la 2FA sull'account, npm CLI 11.15.0 o superiore e Node.js 22.14.0 o superiore. Prima dell'effettiva migrazione, è consigliabile consultare nuovamente la documentazione più recente e verificare le versioni dei runner in uso.
Si raccomanda anzitutto di limitare l'ambito del token su un singolo pacchetto a basso impatto e fare pratica con l'invio allo staging, la revisione da parte del manutentore e la verifica del risultato della pubblicazione. Se in caso di errore si ricorre subito al vecchio token con privilegi più ampi come bypass, i confini appena separati perdono di significato. Anche il ritardo nell'approvazione deve poter essere gestito come uno stato normale.
Domande da porsi nel confronto con il trusted publishing
npm offre anche il trusted publishing basato su OIDC. È opportuno verificare prima se sia adatto all'ambiente CI supportato e alle modalità di approvazione del team, senza considerare a priori il token stage-only come la soluzione definitiva per tutti. Per le automazioni che necessitano ancora dell'uso di token, questa novità può essere vista come un'opzione per una transizione graduale.
L'annuncio ufficiale indica gennaio 2027 come data obiettivo per la rimozione della pubblicazione diretta tramite token bypass-2FA. Piuttosto che fare congetture su tutti i dettagli implementativi definitivi, è più pratico predisporre fin da ora l'elenco dei flussi di lavoro interessati e individuare i responsabili della migrazione. Eventuali modifiche al calendario dovranno essere verificate tramite i successivi annunci ufficiali.
Criteri per decidere l'adozione
Questo articolo non intende sostenere l'esistenza di un ampio consenso nella community né dichiarare un tasso effettivo di riduzione degli incidenti. Si limita a proporre procedure operative verificabili basate sul comportamento ufficiale della nuova funzionalità. La capacità di chiarire cosa spetti all'automazione e cosa debba verificare una persona rappresenta il punto di partenza per decidere se adottarla.
Le azioni da compiere fin da oggi consistono nell'individuare dove vengono utilizzati gli attuali token di rilascio, definire le condizioni che determinano il completamento della pubblicazione e stabilire le prove necessarie per una singola approvazione. Solo gestendo contemporaneamente la limitazione dei privilegi e la qualità della revisione, la fase di staging risulterà davvero vantaggiosa.