Semantic Release no Node.js

semantic-release automatiza o ciclo de release de um projeto Node.js. A ferramenta analisa commits desde a última tag, determina a próxima versão semântica, gera notas, cria tag Git, publica pacotes e notifica serviços integrados. O objetivo é eliminar decisões manuais inconsistentes e tornar cada release consequência direta das mudanças registradas.

Por padrão, mensagens como fix, feat e BREAKING CHANGE são traduzidas em patch, minor e major. Uma execução sem commits relevantes não publica nova versão.

Quando usar

semantic-release funciona melhor quando:

• o projeto possui histórico convencional;
• releases acontecem pela integração contínua;
• a branch principal está protegida;
• testes e builds são confiáveis;
• o pacote pode ser publicado automaticamente;
• a equipe aceita versões calculadas por regras.

Projetos que precisam de aprovação editorial detalhada ou agrupamento manual de mudanças podem preferir Changesets.

Instalação

npm install -D semantic-release

Adicione:

{
  "scripts": {
    "semantic-release": "semantic-release"
  }
}

Não execute releases reais em máquinas de desenvolvimento. Use dry-run para diagnóstico.

Configuração básica

Crie release.config.mjs:

export default {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    '@semantic-release/npm',
    '@semantic-release/github',
  ],
};

Os plugins padrão executam análise de commits, geração de notas, publicação npm e release no GitHub.

Instalando plugins explicitamente

npm install -D \
  @semantic-release/commit-analyzer \
  @semantic-release/release-notes-generator \
  @semantic-release/npm \
  @semantic-release/github

Fixe versões no lockfile. Plugins participam da publicação e recebem acesso a credenciais.

Como a versão é calculada

Com a convenção padrão:

fix(cache): evita expiração duplicada

gera patch.

feat(api): adiciona paginação por cursor

gera minor.

feat(api)!: remove paginação por offset

ou:

refactor(config): altera precedência

BREAKING CHANGE: variáveis de ambiente agora sempre prevalecem.

gera major.

Fluxo interno

A execução segue etapas:

1. verifica condições e credenciais;
2. encontra a última release pelas tags;
3. analisa commits novos;
4. calcula versão;
5. valida a release;
6. gera notas;
7. prepara artefatos;
8. publica;
9. cria tag e release;
10. notifica sucesso ou falha.

Plugins podem participar de cada etapa.

Conventional Commits

O resultado depende da qualidade das mensagens. Valide títulos de pull request ou commits com commitlint. Em squash merge, o título final precisa seguir a convenção.

Um commit classificado incorretamente pode publicar uma versão errada. Corrija antes de entrar na branch de release.

Dry-run

npx semantic-release --dry-run

O dry-run mostra última tag, commits, versão prevista e notas sem publicar. Ainda pode exigir acesso ao repositório remoto para validar permissões.

GitHub Actions

name: Release
on:
  push:
    branches: [main]
permissions:
  contents: write
  issues: write
  pull-requests: write
  id-token: write
jobs:
  release:
    runs-on: ubuntu-latest
    environment: npm
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm run typecheck
      - run: npm test
      - run: npm run build
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fetch-depth: 0 permite analisar tags e histórico. Configure autenticação npm com trusted publishing ou token granular.

Proteção de credenciais

Prefira OIDC para npm quando disponível. Se usar token:

• crie token granular;
• limite aos pacotes necessários;
• não use token pessoal amplo;
• armazene em secrets do ambiente;
• não execute em pull requests externos;
• revogue ao detectar exposição.

Proveniência npm

O plugin npm pode publicar proveniência em ambientes compatíveis. A declaração liga pacote, repositório e workflow, melhorando rastreabilidade da cadeia de suprimentos.

Branches de release

Uma configuração pode incluir canais:

export default {
  branches: [
    'main',
    { name: 'next', channel: 'next', prerelease: true },
    { name: 'beta', prerelease: true },
    '1.x',
  ],
};

main publica no canal padrão. next e beta publicam pré-releases. Uma branch como 1.x pode receber manutenção de uma linha antiga.

Dist-tags

Canais viram tags npm como latest, next e beta. Consumidores escolhem:

npm install @empresa/pacote@next

Evite promover uma pré-release ao canal principal sem testes.

Release notes

@semantic-release/release-notes-generator agrupa commits. Mensagens claras produzem notas úteis. Commits internos podem ser ocultados por regras de análise.

Regras personalizadas

[
  '@semantic-release/commit-analyzer',
  {
    preset: 'conventionalcommits',
    releaseRules: [
      { type: 'docs', scope: 'api', release: 'patch' },
      { type: 'refactor', release: 'patch' },
      { type: 'chore', release: false },
    ],
  },
]

Personalize somente quando houver regra de negócio clara. Regras excessivas tornam versões difíceis de prever.

Publicar changelog no repositório

O plugin changelog gera arquivo, e o plugin git pode commitá-lo:

npm install -D @semantic-release/changelog @semantic-release/git

Isso adiciona commits automatizados à branch. Avalie se a proteção permite e evite loops no CI. Releases do GitHub já fornecem histórico sem alterar o repositório.

Pacotes npm

O plugin npm executa preparação e publicação. Configure files, exports, build e publishConfig. Teste com:

npm pack --dry-run

Se o projeto é uma aplicação e não deve publicar no npm:

{
  "private": true
}

Remova o plugin npm e use tags/releases para versionar imagens ou binários.

Monorepos

semantic-release é naturalmente orientado a uma release por repositório. Para pacotes independentes em monorepo, a configuração fica mais complexa e pode exigir plugins específicos. Changesets costuma ser mais simples nesse cenário.

Build e prepare

O build deve acontecer antes da release ou no passo prepare. Prefira testar o mesmo artefato que será publicado. Evite reconstruir de maneira diferente após os testes.

Falhas parciais

Publicações envolvem Git, npm e serviços externos. Uma falha após publicar no npm pode impedir a criação da release no GitHub. Reexecutar precisa ser idempotente: a ferramenta reconhece versões já publicadas e continua quando possível.

Não altere nem reutilize uma versão publicada.

Tags existentes

semantic-release depende de tags corretas. Migrações de processo devem alinhar tags antigas, versão do package.json e branch. Execute dry-run antes da primeira release automática.

Permissões mínimas

Conceda apenas o necessário. O workflow geralmente precisa escrever contents para tag/release e, opcionalmente, issues e pull requests para comentários. Remova permissões não usadas.

Auditoria

Registre logs, preserve provenance, use environments protegidos e monitore alterações em workflows e plugins. Uma mudança no arquivo de release é mudança de produção.

Semantic Release ou Changesets

Use semantic-release quando commits determinam versões e a automação deve publicar imediatamente após merge. Use Changesets quando cada PR declara impacto e a equipe prefere um PR de versão revisável. Os dois não devem controlar simultaneamente as mesmas versões.

Fluxo recomendado

Valide commits, execute release somente após testes, use histórico completo, OIDC, proveniência, branches protegidas e dry-run na migração. Combine com Conventional Commits, Publicação de Pacotes npm, Changesets no Node.js e segurança de Supply Chain.

Consulte a documentação oficial atual do semantic-release e o repositório oficial do projeto.