O trusted publishing do npm agora pode mover dist-tags via OIDC

O GitHub anunciou em 30 de setembro de 2026 que o trusted publishing (publicação confiável) do npm agora pode gerenciar dist-tags. São os rótulos como latest que decidem qual versão de um pacote as pessoas instalam. Os pipelines de release podem mover esses rótulos com um token de login de curta duração, em vez de um token de acesso do npm armazenado. Isso elimina um motivo comum para manter um segredo do npm de longa duração dentro de um sistema de CI.

A permissão é opcional (opt-in). Ela começa desativada em todas as configurações, antigas ou novas, então ninguém ganha o poder de mover latest sem pedir por isso.

O que são o trusted publishing e as dist-tags

O trusted publishing permite que um job de CI, como um workflow do GitHub Actions, publique no npm sem uma senha ou um token armazenados. O job prova quem é com OIDC, sigla de OpenID Connect, um jeito padrão de emitir tokens de identidade de curta duração. O registro do npm confere esse token com uma configuração criada pelo dono do pacote e então permite a ação.

Uma dist-tag é um ponteiro com nome para uma versão de um pacote. A tag latest é a que a maioria das instalações segue. Os projetos costumam adicionar outras, como next ou beta, para versões de teste. Até agora, o trusted publishing conseguia lançar um pacote, mas não mover esses ponteiros, então as equipes mantinham um token de longa duração para essa etapa.

O que a nova permissão permite

Cada configuração de trusted publishing agora tem uma opção chamada "Allow npm dist-tag", segundo o changelog do GitHub. Quando ela está ativada, o job de CI pode adicionar, remover e promover dist-tags. A documentação do npm lista os comandos correspondentes: npm dist-tag ls, npm dist-tag add e npm dist-tag rm.

O GitHub reforça o padrão. "Ela vem desativada por padrão tanto nas configurações novas quanto nas existentes, então nenhuma configuração ganha automaticamente uma nova capacidade", diz o changelog.

A permissão é separada da publicação. Segundo a documentação, uma configuração pode ter permissão para fazer staging de pacotes e gerenciar dist-tags sem ter permissão para executar npm publish. A documentação acrescenta que as configurações criadas depois de 3 de setembro de 2026 podem fazer staging de pacotes automaticamente, mas o acesso às dist-tags ainda precisa ser ativado manualmente.

Uma regra importa para a segurança. Uma alteração de dist-tag é permitida "se o token OIDC recebido corresponder a qualquer uma das configurações com a permissão ativada", escreve o GitHub. Por isso, cada configuração com a caixa marcada é mais um caminho para mover latest.

Requisitos e limites

A documentação do npm define estes mínimos:

Requisito	O que diz a documentação do npm
npm CLI para dist-tags via OIDC	11.21.0 ou posterior
npm CLI para trusted publishing em geral	11.5.1 ou posterior
Node.js	22.14.0 ou posterior
GitHub Actions	Apenas runners hospedados pelo GitHub
GitLab CI/CD	Apenas runners compartilhados do GitLab.com
CircleCI	Apenas CircleCI cloud
Runners auto-hospedados	Ainda não suportados

A documentação diz que os runners auto-hospedados "estão planejados para versões futuras". As fontes divergem sobre o suporte a serviços de CI. Um post na DEV Community de um desenvolvedor chamado Leo também menciona Buddy e Jenkins, este último por meio de plugins, mas a própria documentação do npm lista apenas os três serviços acima.

Por que as dist-tags são um alvo

Mover uma dist-tag é tão poderoso quanto publicar. O post de Leo classifica o controle das dist-tags como um risco sério para a cadeia de suprimentos, porque um atacante capaz de reescrever latest pode direcionar cada nova instalação para uma versão ruim. Releases maliciosos são um padrão real: em agosto, versões envenenadas do crate Rust arrayref executaram um payload remoto durante os builds.

Leo também alerta para uma falha humana. Equipes que dão de cara com um release bloqueado podem marcar a caixa em todas as configurações para fazer o problema sumir. Em vez disso, o post recomenda uma única configuração dedicada a releases, com correspondência estrita: um arquivo de workflow específico, um ambiente protegido e uma etapa de aprovação manual.

O que isso significa para desenvolvedores

Atualize primeiro o npm CLI no seu job de release. Alterações de dist-tags via OIDC exigem o npm 11.21.0 ou posterior e o Node.js 22.14.0 ou posterior. Um CLI mais antigo em uma imagem de CI fixada vai falhar mesmo com a opção ativada.

Ative a permissão em um único lugar. Como qualquer configuração correspondente pode, sozinha, mover latest, ative-a na sua configuração de release e deixe as configurações de staging e de teste desativadas. Revise a lista após cada mudança.

Restrinja bem a configuração. Vincule-a ao arquivo de workflow exato que gera os releases e exija um ambiente protegido com uma etapa de aprovação. Assim, nem um workflow de pull request nem um job paralelo comprometido conseguirá mover as suas tags.

Apague o token antigo quando a troca estiver funcionando. O objetivo desta mudança é parar de armazenar segredos do npm de longa duração no CI. Depois que um release der certo via OIDC, remova o token que sobrou dos segredos do seu CI e revogue-o no npm.

Mantenha um token apenas onde for indispensável. Se você faz builds em runners auto-hospedados, o trusted publishing ainda não atende você. Limite esse token aos pacotes de que ele precisa e faça a rotação dele periodicamente até que o npm passe a suportar runners auto-hospedados.

Confira as suas tags após cada release. Execute npm dist-tag ls no seu pacote e confirme que latest aponta para onde você espera. É uma verificação de dois segundos que pega tanto erros quanto ataques.