Fluxos de Release Facilitados Com Changesets

Publicar pacotes npm não deveria exigir scripts personalizados, incrementos manuais de versão ou lembrar quais pacotes mudaram desde o último release. No entanto, muitas equipes ainda montam processos de release frágeis que falham nos piores momentos.

Changesets resolve isso capturando a intenção de release no momento da contribuição e automatizando o resto. Este artigo aborda como construir um fluxo de trabalho moderno de release com Changesets—incluindo publicação confiável no npm, versionamento de monorepo com Changesets e releases de pacotes via GitHub Actions—sem o fardo de manutenção.

O Fluxo de Trabalho Central do Changesets Release

O fluxo de trabalho segue três fases:

1. Contribuidores adicionam arquivos changeset descrevendo o que mudou e quão significativo é (patch, minor, major)
2. CI cria um PR de versionamento que agrega todos os changesets em incrementos de versão e entradas de changelog
3. Merge do PR aciona a publicação no npm com proveniência adequada

Cada changeset é um arquivo markdown em .changeset/ contendo frontmatter que especifica os pacotes afetados e o tipo de incremento semver, além de um resumo legível. Quando múltiplos changesets existem, Changesets calcula o maior incremento de versão necessário por pacote—duas mudanças minor não se tornam dois incrementos minor.

Para monorepos, isso é significativamente importante. Changesets automaticamente gerencia atualizações de dependências internas quando um pacote workspace depende de outro que está sendo lançado.

Releases de Pacotes via GitHub Actions: A Abordagem Moderna

A maioria dos tutoriais mostra workflows usando secrets NPM_TOKEN. Essa abordagem funciona, mas traz riscos de segurança—tokens de longa duração podem vazar e requerem rotação manual.

Publicação confiável no npm usando tokens OIDC é agora o método preferido. Em vez de armazenar credenciais, seu workflow do GitHub Actions solicita um token de curta duração diretamente do npm durante a etapa de publicação. O token existe apenas para aquele job e não pode ser extraído ou reutilizado.

Para habilitar isso:

1. Vincule seu pacote npm ao seu repositório GitHub nas configurações do pacote no npm
2. Configure seu workflow com permissão id-token: write
3. Certifique-se de que a proveniência está habilitada (npm pode gerá-la automaticamente para publicadores confiáveis, ou via flag --provenance em CLIs mais recentes)

A proveniência npm adiciona atestação criptográfica provando que o pacote foi construído a partir de um commit específico no seu repositório. Usuários podem verificar exatamente qual código-fonte produziu o artefato publicado.

Limitações atuais a conhecer: publicação confiável no npm requer repositórios públicos. Repositórios privados ainda precisam da abordagem legada NPM_TOKEN. Adicionalmente, a changesets/action oficial tem suporte em evolução para OIDC—verifique a documentação atual para os padrões de integração mais recentes.

Versionamento de Monorepo Com Changesets

Changesets foi projetado para monorepos desde o início. Opções-chave de configuração em .changeset/config.json controlam o comportamento multi-pacote:

• linked: Agrupa pacotes que devem sempre compartilhar o mesmo número de versão
• fixed: Similar ao linked, mas todos os pacotes são incrementados juntos mesmo se apenas um mudou
• updateInternalDependencies: Controla se dependentes recebem incrementos patch quando suas dependências são atualizadas

Quando um contribuidor executa a CLI do changeset em um monorepo, ele seleciona quais pacotes sua mudança afeta. O PR de versionamento então mostra exatamente quais pacotes serão lançados e em quais versões.

Armadilhas Comuns de CI

Problemas de permissão causam a maioria das falhas de workflow. O token do GitHub precisa de acesso de escrita para criar PRs e fazer push de tags. Para publicação no npm, certifique-se de que seu token (ou configuração OIDC) tem direitos de publicação para todos os pacotes no seu escopo.

Conflitos de automação de PR acontecem quando regras de proteção de branch bloqueiam o bot de fazer push de commits de versão. Permita que o bot do GitHub Actions contorne a proteção ou use uma conta de bot dedicada com permissões apropriadas.

Ordem de publicação de múltiplos pacotes importa quando pacotes dependem uns dos outros. Changesets lida com isso automaticamente, mas falhas de rede no meio da publicação podem deixar seu monorepo em um estado inconsistente. A changesets/action inclui lógica de retry, mas entender esse modo de falha ajuda na recuperação.

Changesets esquecidos são o erro mais comum de contribuidores. O bot Changeset comenta em PRs sem changesets, mas você também pode adicionar verificações de CI que falham quando changesets são necessários mas ausentes.

Estruturando Seu Workflow Hoje

A maioria das equipes executa a action Changesets em cada push para main. A action abre ou atualiza um PR “Version Packages” quando changesets não lançados existem, ou publica pacotes quando o PR de versão é mergeado.

Isso cria uma cadência natural de release: faça merge de features ao longo da semana, depois faça merge do PR de versão quando estiver pronto para lançar. Sem edição manual de versão, sem esquecer de atualizar changelogs, sem publicar os pacotes errados.

Conclusão

Um workflow de release bem configurado com Changesets remove a sobrecarga cognitiva dos releases de pacotes. Contribuidores declaram intenção antecipadamente, CI lida com a coordenação, e publicação confiável no npm garante artefatos seguros e verificáveis.

Comece com uma configuração de pacote único para entender o fluxo, depois estenda para monorepos conforme necessário. O investimento inicial de configuração se paga rapidamente em ansiedade reduzida de release e menos momentos “ops, versão errada”.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.