Releases e tags no GitHub
A release do GitHub é a publicação de uma versão do projeto, montada sobre uma tag do Git que marca o commit exato daquela versão. Ela junta as notas da versão, os arquivos de código-fonte gerados pelo GitHub e os binários anexados, por isso você baixa ou instala uma versão sabendo qual commit ela representa.
Ficha e sumário da página
- Referência técnica
- GitHub CLI v2.104.0
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
A tag marca o commit, a release publica
A tag é um recurso do Git: um nome fixo, como v1.4.0, preso a um commit específico do histórico. A branch avança a cada commit novo, enquanto a tag continua apontando para o mesmo lugar, por isso ela serve como endereço estável de uma versão.
A release é um recurso do GitHub construído sobre a tag. A documentação diz que as releases se baseiam em tags do Git e acrescentam o que a tag não guarda: as notas da versão e os links para os arquivos. A data da tag e a data da release podem ser diferentes, porque as duas podem ser criadas em momentos distintos: a tag pode existir desde o commit, enquanto a release sai dias depois, quando as notas ficam prontas.
O que uma release carrega
Toda release ganha dois arquivos gerados pelo GitHub: um zip e um tarball do repositório no ponto da tag. Além deles, a release aceita até mil arquivos anexados, cada um com menos de 2 GiB, sem limite no tamanho total nem no tráfego de download. É nesses anexos que ficam o binário compilado, o tarball de uma biblioteca e o arquivo de somas de verificação.
As notas vêm do seu changelog ou da geração automática, que monta o texto a partir dos pull requests incluídos desde a release anterior. A geração usa um modelo padrão que você pode personalizar. Os inscritos no repositório podem receber aviso só das releases novas, sem as outras notificações do projeto, o que faz da release o canal de anúncio de uma versão.
- RascunhoGuarda a release sem publicar, enquanto você anexa os arquivos e revisa as notas.
- Pré-releaseAvisa que a versão ainda não está pronta para produção e pode ser instável.
- LatestA release marcada como a mais recente. Sem escolha manual, o GitHub usa o versionamento semântico.
- ImutávelDepois de publicada, não aceita troca de arquivos nem mudança da tag.
O modo imutável, ligado no repositório ou na organização, impede que um arquivo anexado seja trocado depois da publicação. Com ele ligado, o título, as notas e a marcação de pré-release ou de mais recente continuam editáveis, mas os arquivos anexados e a tag ficam fixos enquanto a release existir. Por isso a documentação recomenda criar a release como rascunho, anexar tudo e só então publicar.
O fluxo de versão da Promovaweb
O contrato de publicação da Promovaweb trata a release como a última peça de um processo que vale para o Hub e para cada repositório do ecossistema. Nesse contrato, nenhuma alteração publicada sai sem versão. O caminho vai do changelog até a conferência da release no GitHub:
Changelog e versão
CHANGELOG.mdO changelog registra a mudança e a versão avança pelo SemVer.
Validações
npm testAs validações do repositório rodam com a versão nova.
Commit e tag
git tag v1.4.0Um commit identificável recebe uma tag nova, que não se move depois de publicada.
GitHub Release
gh release create v1.4.0A release usa a mesma tag e as notas do changelog.
Push e conferência
gh release view v1.4.0Commit e tag chegam à main e a release remota é conferida.
Quando uma alteração atinge um submódulo e o Hub, a ordem importa. O submódulo publica primeiro a versão dele, com changelog, tag e release. Só depois ele envia tudo para a main. Na sequência, o Hub atualiza o ponteiro do submódulo e publica a própria versão. Assim, cada release do Hub aponta para um commit que já tem release no submódulo.
O npm segue a mesma lógica com uma etapa local. Os workflows podem criar a tag e a release e anexar o tarball, mas a publicação no npm acontece pela máquina local, a partir do tarball do commit da tag. Quando a release traz o arquivo SHA256SUMS, o hash do tarball precisa bater com o valor registrado nele para a publicação seguir. A versão só fica completa quando o npm mostra o mesmo número da tag.
Releases pelo terminal
O GitHub CLI cria e consulta releases pelos comandos do grupo gh release. O gh release create v1.4.0 cria a release e, quando a tag ainda não existe, cria a tag a partir do estado mais recente da branch padrão. A opção --generate-notes monta as notas a partir dos pull requests, enquanto --notes-file usa o texto de um arquivo, como as notas copiadas do changelog. A opção --prerelease marca a versão como pré-release, enquanto --draft guarda a release como rascunho.
gh release create v1.4.0 --notes-file notas.mdCria a release com as notas de um arquivo.Na publicação de cada versão, com o texto do changelog.gh release listLista as releases do repositório, da mais nova à mais antiga.Na conferência de qual versão está publicada.gh release view v1.4.0Mostra notas, arquivos anexados e a tag da release.Na conferência final da publicação.gh release download v1.4.0Baixa os arquivos anexados à release.Na publicação do tarball no npm pela máquina local.As releases do próprio GitHub CLI seguem esse formato: cada versão do cli/cli sai com tag, notas e binários para cada sistema. O changelog do GitHub CLI acompanha essas releases em português. O próximo assunto é a própria ferramenta, o gh, com o que ela faz no terminal e nos scripts, na página GitHub CLI.