Ir para o conteúdo
Promovaweb

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
  1. A tag marca o commit, a release publica
  2. O que uma release carrega
  3. O fluxo de versão da Promovaweb
  4. Releases pelo terminal

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:

  1. Changelog e versão

    CHANGELOG.md

    O changelog registra a mudança e a versão avança pelo SemVer.

  2. Validações

    npm test

    As validações do repositório rodam com a versão nova.

  3. Commit e tag

    git tag v1.4.0

    Um commit identificável recebe uma tag nova, que não se move depois de publicada.

  4. GitHub Release

    gh release create v1.4.0

    A release usa a mesma tag e as notas do changelog.

  5. Push e conferência

    gh release view v1.4.0

    Commit e tag chegam à main e a release remota é conferida.

O fluxo de versão dos projetos da Promovaweb, do contrato interno de publicação: a release no GitHub é a última etapa e a conferência remota fecha a publicação.

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.

ComandoO que fazQuando aparece
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.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.