semantic-release no Node.js

O semantic-release no Node.js automatiza cálculo da próxima versão, geração de release notes, criação de tag, publicação no npm e release no GitHub. Em vez de alguém escolher manualmente entre patch, minor ou major, a ferramenta analisa commits desde a última tag e aplica regras baseadas em Conventional Commits.

Esse fluxo reduz erros de versão e garante que uma release só aconteça depois que o CI foi aprovado. Porém, a automação depende da qualidade das mensagens de commit, da segurança das credenciais e de branches protegidas. Um feat classificado incorretamente pode gerar minor, enquanto um breaking change não marcado pode sair com versão incompatível.

Neste guia, você aprenderá a instalar semantic-release, configurar plugins, GitHub Actions, npm, branches, pré-releases, maintenance releases, dry-run, provenance e práticas de segurança.

O que é semantic-release?

O site oficial semantic-release.org apresenta a ferramenta como automação completa de versionamento e publicação. Depois de um build aprovado em uma branch de release, ela:

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

Quando usar?

semantic-release funciona bem quando:

• há um pacote ou produto com releases frequentes;
• commits ou títulos de PR seguem convenção;
• CI é obrigatório;
• a equipe aceita release automática após merge;
• branches e credenciais são protegidas;
• a versão vem do histórico, não de aprovação manual por pacote.

Em monorepos com múltiplos pacotes independentes, Changesets pode ser mais explícito. Veja Changesets no Node.js.

Conventional Commits

Na configuração padrão:

• fix gera patch;
• feat gera minor;
• BREAKING CHANGE gera major;
• commits sem impacto podem não gerar release.

Consulte Conventional Commits no Node.js.

Instalação

npm install --save-dev semantic-release

Adicione um script:

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

Não execute release automaticamente durante instalação ou build local.

Configuração mínima

Crie release.config.mjs:

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

Instale os plugins explicitamente quando não vierem na composição utilizada:

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

package.json

{
  "name": "@empresa/domain",
  "version": "0.0.0-development",
  "private": false,
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

O valor local de version pode ser mantido conforme a estratégia adotada. semantic-release determina a versão publicada a partir das tags e commits.

Primeiro dry-run

npx semantic-release --dry-run

O dry-run verifica branches, tags, commits e credenciais quando possível, mas não reproduz todos os efeitos de publicação. Execute em clone com histórico completo.

Git history completo

O CI precisa acessar tags e commits anteriores. Checkout raso pode impedir encontrar a última release:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

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
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
          registry-url: https://registry.npmjs.org

      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build
      - run: npx semantic-release

Consulte CI para Node.js com GitHub Actions.

Publicação segura no npm

Prefira trusted publishing por OIDC em vez de token permanente. Configure o pacote no npm para confiar no repositório e workflow exatos, e conceda id-token: write somente ao job de release.

Veja Publicar Pacote no npm.

Plugin commit-analyzer

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

Não crie regras que transformem qualquer chore em release. O changelog e versão devem refletir impacto para consumidores.

Plugin release-notes-generator

Gera notas a partir dos commits. Configure preset igual ao analyzer para evitar interpretações diferentes.

[
  '@semantic-release/release-notes-generator',
  { preset: 'conventionalcommits' }
]

Plugin npm

@semantic-release/npm atualiza versão durante a preparação e publica quando npmPublish não está desabilitado.

[
  '@semantic-release/npm',
  {
    npmPublish: true,
    tarballDir: 'dist-packages'
  }
]

Confirme files, exports, types e conteúdo com npm pack --dry-run.

Plugin GitHub

@semantic-release/github cria release, publica assets e pode comentar em issues ou pull requests. Conceda apenas permissões necessárias.

Changelog no repositório

semantic-release prioriza notas e releases automatizadas. Se precisa atualizar CHANGELOG.md, use plugins específicos com cuidado. Comitar arquivos de release de volta à main pode disparar novo workflow; configure mensagem com skip ou condições.

Branches de release

export default {
  branches: [
    'main',
    { name: 'next', prerelease: true },
    { name: 'beta', prerelease: true },
    '+([0-9])?(.{+([0-9]),x}).x'
  ]
};

A expressão final representa maintenance branches, conforme padrões suportados pela ferramenta.

Pré-release

Commits em beta podem gerar:

2.0.0-beta.1

O pacote deve ser publicado com dist-tag correspondente, não latest. semantic-release controla canais conforme a configuração de branches.

Maintenance releases

Uma branch 1.x pode receber correções compatíveis para consumidores que ainda não migraram para 2.x. Cherry-pick apenas mudanças apropriadas e mantenha testes para a versão de runtime suportada.

Tags

Por padrão, tags seguem v${version}. Customize:

export default {
  tagFormat: 'package-v${version}'
};

Não altere o formato em projeto existente sem planejar como a ferramenta encontrará releases anteriores.

Primeira release

Se não há tag anterior, todos os commits relevantes podem ser analisados. Limpe histórico ou configure uma tag inicial quando necessário. Confirme com dry-run.

Branch protection

A release automática é tão segura quanto a branch:

• exija pull request;
• exija reviews;
• exija checks;
• bloqueie force push;
• restrinja alteração do workflow;
• use CODEOWNERS para arquivos de release;
• proteja ambientes.

Pull requests de forks

Não disponibilize credenciais de release a código não confiável. O workflow de publicação deve rodar somente após merge em branch protegida.

Versão do Node.js

semantic-release atualiza sua política de runtime. Fixe versões compatíveis no lockfile e no CI. Leia os requisitos atuais antes de atualizar.

Plugins de terceiros

Plugins executam código com credenciais de release. Avalie:

• manutenção;
• permissões;
• dependências;
• proveniência;
• necessidade real.

Shareable config

Organizações podem publicar:

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

No projeto:

export default {
  extends: ['@empresa/semantic-release-config']
};

Fixe a configuração e revise upgrades como código de supply chain.

Monorepos

semantic-release puro é mais natural para uma unidade versionada. Em monorepos independentes, plugins ou execuções por pacote aumentam complexidade. Changesets costuma ser mais simples para decisões explícitas.

Veja npm Workspaces no Node.js.

Sem publicação npm

Aplicações podem usar semantic-release apenas para tags e releases:

[
  '@semantic-release/npm',
  { npmPublish: false }
]

Ou remover o plugin npm e usar comandos de deploy em etapa própria.

Docker e imagens

Um plugin exec pode construir e publicar imagens, mas separe responsabilidades quando possível. Use a versão calculada como tag, e evite publicar imagem antes de todos os checks.

Falha parcial

Se npm foi publicado e a criação da release falhou, a versão não pode ser republicada. Corrija a etapa posterior sem tentar sobrescrever. Plugins devem ser idempotentes sempre que possível.

Dry-run local

GITHUB_TOKEN=token-de-leitura npx semantic-release --dry-run --no-ci

Não use token real em histórico do shell ou documentação. Em muitos casos, execute dry-run no CI com ambiente protegido.

Logs

semantic-release registra etapas e plugins. Preserve logs de falha como artifact, mas redija secrets. Evite debug permanente se ele expõe headers ou configuração sensível.

Erros comuns

• Checkout raso: última tag não é encontrada.
• Commit errado: versão incorreta.
• Breaking sem footer: major não sai.
• Token permanente: risco de comprometimento.
• Release em PR: código não confiável acessa segredo.
• Branch sem proteção: qualquer merge publica.
• Plugin excessivo: supply chain aumenta.
• Monorepo complexo: versões cruzadas ficam difíceis.

Fluxo recomendado

1. Adote Conventional Commits.
2. Valide títulos ou commits.
3. Proteja main.
4. Execute CI completa.
5. Use checkout com histórico.
6. Rode dry-run.
7. Configure OIDC para npm.
8. Execute semantic-release após merge.
9. Monitore package, tag e release.
10. Corrija falhas sem reutilizar versão.

Conclusão

O semantic-release no Node.js automatiza uma release do commit até o registry. A ferramenta calcula SemVer, gera notas, cria tags e publica somente após um build aprovado.

O benefício depende de histórico correto e CI segura. Use Conventional Commits, branches protegidas, histórico completo e credenciais temporárias. Com plugins mínimos e dry-run, releases se tornam consistentes sem transformar versionamento em uma decisão manual e emocional.