Tokens stage-only do npm: que evidências manter ao separar a automação de deploy da aprovação final
Separar o privilégio do CI de criar um pacote da permissão para publicá-lo para os usuários torna a responsabilidade final da release muito mais clara. No entanto, adicionar um simples botão de aprovação não elimina os riscos na cadeia de suprimentos. É preciso primeiro definir o que o aprovador deve verificar.
Em 18 de setembro, o GitHub anunciou que os tokens de acesso granular do npm agora contam com a opção de permissão de escrita stage-only. Nesse fluxo, a automação envia uma versão para um estado pendente de revisão, e o mantenedor aprova a publicação por meio de 2FA. A seguir, apresentamos as alterações oficiais e as propostas editoriais para colocá-las em operação.
Bloquear a publicação direta não é o mesmo que remover permissões de escrita
De acordo com as orientações oficiais, é possível executar npm stage publish com esse token, mas a publicação direta por meio de npm publish é recusada. Essa restrição se aplica mesmo se houver configurações de bypass de 2FA para automação. Esse recurso não altera automaticamente o comportamento dos tokens existentes; sua adoção é opcional.
É preciso atentar para o fato de que outras permissões de escrita no pacote continuam ativas, como mover dist-tags e marcar versões como depreciadas (deprecation). Não se deve interpretar o nome stage-only como um token somente leitura ou inofensivo. O escopo de pacotes permitidos, o local de armazenamento dos segredos, as identidades com acesso e os procedimentos de revogação ainda exigem gerenciamento.
Defina o pacote de release que o aprovador irá comparar
O conteúdo a seguir não constitui uma configuração obrigatória do npm, mas sim uma sugestão operacional para equipes menores. Em cada solicitação de aprovação, reúna o commit de origem, o pacote e a versão de destino, os resultados dos testes, a lista de arquivos incluídos no pacote e o resumo das alterações. Se o aprovador precisar juntar evidências espalhadas por múltiplos logs de CI, a revisão facilmente se degradará em um clique protocolar.
A revisão do código-fonte e a revisão dos arquivos de distribuição são etapas distintas. Arquivos que não estavam no repositório podem ser incluídos durante o processo de build, ou arquivos necessários podem ser omitidos. A equipe pode adotar como princípio a geração de materiais de revisão com base nos artefatos efetivamente enviados e, caso esses artefatos sofram alterações após a verificação, tratá-los como um novo objeto de revisão.
Existe um estado de espera mesmo após o CI ficar verde
Se as automações anteriores tratavam o sucesso de um comando como a conclusão da release, a forma de comunicar o status precisa mudar. A abordagem recomendada divide as etapas em envio concluído, aprovação pendente e publicação concluída, registrando as evidências de validação de cada uma. Em notificações, informar a etapa atual e o responsável é muito mais útil para os operadores do que uma mensagem genérica de sucesso.
Em um cenário hipotético em que um CI noturno envia uma nova versão, mas o responsável só realiza a revisão no dia seguinte, o comunicado de lançamento voltado aos usuários não deve ser disparado no momento da submissão. Estruture o processo para que publicações de documentação ou anúncios só ocorram após a confirmação da publicação definida pela equipe. Também deve haver um acordo prévio sobre quem realiza a revisão e em que momento descartar submissões pendentes quando a fila se acumular.
Valide a migração com um único pacote pequeno
Atualmente, os pré-requisitos descritos nas instruções oficiais incluem um pacote npm existente, permissões para publicar o pacote, 2FA configurado na conta, npm CLI 11.15.0 ou superior e Node.js 22.14.0 ou superior. Antes de iniciar a migração definitiva, consulte a documentação mais recente e verifique a versão dos runners em uso.
Recomendamos limitar inicialmente o escopo do token em um único pacote de menor impacto e praticar o fluxo completo: submissão em staging, revisão pelo mantenedor e validação do resultado da publicação. Se o fluxo for configurado para recorrer imediatamente a tokens antigos de permissão ampla diante de qualquer falha, a separação planejada perderá o sentido. Esperas ou atrasos na aprovação também devem ser tratados como estados normais de operação.
Perguntas para comparar com o trusted publishing
O npm também disponibiliza o trusted publishing com suporte a OIDC. O primeiro passo é avaliar se essa alternativa é compatível com o seu ambiente de CI e com o modelo de aprovação adotado pela equipe; não há motivo para tratar os tokens stage-only como a solução definitiva para todos os times. Para automações que ainda dependem de tokens estáticos, a novidade representa uma opção para conduzir uma migração gradual.
O anúncio oficial aponta janeiro de 2027 como meta para a descontinuação da publicação direta com tokens configurados para bypass de 2FA. Em vez de especular sobre todos os detalhes definitivos de implementação, é mais prático mapear desde já a lista de workflows impactados e designar os responsáveis pela transição. Mudanças no cronograma devem ser acompanhadas pelos comunicados oficiais futuros.
Critérios para decidir sobre a adoção
Este artigo não tem a pretensão de declarar um consenso amplo da comunidade nem promete reduções quantificáveis de incidentes. Trata-se de uma proposta de procedimentos operacionais auditáveis baseada no comportamento oficial do novo recurso. O ponto de partida para decidir pela adoção é saber explicar claramente o que compete à automação e o que deve ser conferido por um ser humano.
O passo prático para hoje é localizar onde os tokens de release atuais estão distribuídos, definir os critérios objetivos que comprovam a publicação concluída e listar as evidências indispensáveis para uma única aprovação. A fase de staging só trará benefícios reais se a restrição de permissões for acompanhada por um processo de revisão de qualidade.