Go CLI Release Kit

Para quem é

Você escreveu uma ferramenta de linha de comando em Go e as pessoas querem instalá-la. A documentação do GoReleaser é boa e gratuita, e um .goreleaser.yaml funcionando leva uma tarde. O resto leva mais tempo: um comando de versão que imprime o commit de verdade, um install.sh que você não teria vergonha de ver em um pipe com curl, uma estratégia de checksums, um CI que faz release a cada tag, uma fórmula do Homebrew sem hash vazio.

Este kit é um esqueleto de repositório que você copia e renomeia. Tudo nele foi executado em um container limpo, e a saída acompanha o kit para você ver o que "funcionou" significou.

O que tem nele

• .goreleaser.yaml para Linux, macOS e Windows em amd64 e arm64. Builds estáticos, -trimpath, versão, commit e data do commit injetados, um arquivo de checksums e um changelog agrupado pelo prefixo do Conventional Commits.
• install.sh, um instalador que verifica o que baixa, com opção de versão fixa e conferência opcional de assinatura GPG.
• Um verificador de reprodutibilidade que compila duas vezes em ambientes limpos separados e compara os resultados.
• Um script de bump de versão que lê os seus commits e escolhe a próxima tag.
• Geradores de Homebrew e Scoop que montam a fórmula e o manifest a partir dos seus checksums reais.
• Templates de CI para GitHub Actions e GitLab: lint, testes com o race detector e release na tag.
• Uma CLI de exemplo só com a biblioteca padrão, com testes, e um guia passo a passo da primeira release com checklist.

O que o instalador recusa

Um instalador que baixa um binário e o executa é um bom lugar para ser rigoroso. Nos testes, o install.sh para, não instala nada e deixa intacta uma instalação existente quando:

• o pacote baixado não bate com o SHA-256 (adulteramos um para conferir),
• o arquivo de checksums não tem entrada para o pacote, ou tem a entrada duas vezes,
• o arquivo de checksums não existe, ou a release não existe,
• a URL é http puro,
• a string de versão é inválida ou vazia,
• a plataforma não é uma das que você compilou. A detecção de arquitetura é testada com um uname falso, incluindo armv7, i686, riscv64, FreeBSD e shells do Windows.

Com uma chave GPG configurada, uma chave errada, um arquivo de checksums modificado, uma assinatura ausente e um arquivo de chave ausente também são recusados, de modo que a assinatura protege o próprio arquivo de checksums.

Builds reproduzíveis, conferidos

O repro-check.sh clona o repositório duas vezes, em diretórios diferentes, com ambiente vazio e cache do Go novo, com dois segundos de intervalo, e compara binários, pacotes e o arquivo de checksums. No projeto de exemplo, 13 de 13 arquivos saíram idênticos. Dois erros propositais, gravar a hora do build nos ldflags e omitir o -trimpath, fizeram todos os arquivos diferirem. Ou seja, a verificação falha quando deve falhar.

Números

As flags -s -w do linker cortam o tamanho do pacote mais ou menos pela metade neste exemplo: o pacote do Linux amd64 tem 770,338 bytes com elas e 1,531,872 sem. O tempo de build depende muito do estado do cache, e o README o lista junto com o ambiente.

Como foi testado

183 checks automatizados em um container Linux limpo com o GoReleaser v2.20.0, mais uma passada de build e testes do exemplo no Go 1.22. Os checks incluem uma release snapshot que gera seis pacotes, a execução do binário Linux gerado com a comparação da saída do --version, a conferência do arquivo de checksums contra os pacotes, um build com tag para o changelog, cerca de 25 casos para o script de bump de versão em repositórios git temporários e o actionlint nos workflows do GitHub.

Requisitos

Go, git e GoReleaser OSS. Docker se você quiser rodar o harness de testes.

Perguntas frequentes

Por que não usar só a documentação do GoReleaser?

Pode usar. A documentação cobre o GoReleaser. Este kit cobre o que está em volta dele e confere se as peças funcionam juntas.

Tem suporte a GitLab?

Sim. Há um template de GitLab CI, com notas sobre a configuração do token.

Posso usar o meu próprio module path e meus nomes?

Pode. O guia da primeira release lista todos os lugares a renomear.

Licença

Use nos seus próprios projetos. O arquivo LICENSE do esqueleto é seu para substituir. Não revenda o kit.

Changelog

• 0.1.0: primeira release.

Ler mais

• Verify a downloaded binary: checksums, GPG, minisign, cosign (em inglês)
• Reproducible Go builds: build twice, compare the hashes (em inglês)
• A GoReleaser v2 config for a small Go CLI, line by line (em inglês)
• What a curl | sh installer for a Go binary should refuse (em inglês)

Quero este

Comprar na Polar: $24

Pagamento, impostos e notas fiscais ficam com a Polar, que atua como merchant of record. Você recebe o link de download assim que concluir a compra.