GitHub Actions para Repositórios Go

Q: A CI deve usar a mesma versão do Go que a produção?

A CI deve atender ou exceder a diretiva go em go.mod. A versão de runtime de produção é separada da toolchain usada para compilar.

Q: Como executar testes com o detector de race?

Adicione um job: go test -race ./... em Linux de 64 bits. Mais lento; geralmente noturno ou apenas para main para economizar tempo de PR.

Q: Como cachear módulos no Actions?

actions/setup-go com cache: true usa hashes de go.sum. Para workspaces, liste todos os go.sum em cache-dependency-path.

Q: Como testar releases de tags na CI?

Dispare o fluxo de trabalho em push: tags: ['v*'], execute o teste completo e, em seguida, anexe artefatos ou execute goreleaser.

Q: Quais permissões a CI precisa?

contents: read para jobs de teste. Escrever ou id-token apenas para jobs de release, assinatura ou implantação.

O GitHub Actions executa as mesmas verificações de go test, lint e higiene de módulos em cada push e pull request.

Fluxos de trabalho bem projetados armazenam módulos em cache, fixam versões do Go e validam merges antes que alterações ruins no go.mod cheguem ao trunk.

Resumo

Um fluxo de trabalho mínimo de Go CI configura o Go, baixa módulos com cache, executa testes e vet, e falha se go mod tidy alterasse arquivos.

Adicione golangci-lint, detecção de race e jobs de release que criam tags semver quando os mantenedores precisam de automação.

Mantenha segredos com escopo para busca de dependências privadas GOPRIVATE e credenciais de publicação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
          cache: true
      - run: go test ./...
      - run: go vet ./...
      - run: go mod tidy && git diff --exit-code go.mod go.sum

Quando usar isso:

Novo repositório de módulo Go precisando de verificações de PR antes do merge.
Substituindo a cultura ad hoc de go test apenas local.
Adicionando automação de release após desvios manuais de git tag.
Aplicando grafos de módulos organizados em monorepos com filtros de caminho.

Exemplo de Trabalho

CI completa mais job de lint para github.com/myorg/widget:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
 
permissions:
  contents: read
 
env:
  GOTOOLCHAIN: local
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache-dependency-path: |
            go.sum
            **/go.sum
 
      - name: Test
        run: go test -count=1 ./...
 
      - name: Vet
        run: go vet ./...
 
      - name: Verificação Mod tidy
        run: go mod tidy && git diff --exit-code go.mod go.sum
 
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest

O que isso demonstra:

go-version-file: go.mod alinha a CI com o nível da toolchain declarado no módulo.
Caminhos de cache incluem arquivos go.sum aninhados para repositórios multi-módulo.
Job de lint separado mantém o feedback paralelo sem bloquear o início dos testes.

Análise Detalhada

Como Funciona

actions/checkout clona a referência de merge do PR ou o SHA do push.
setup-go instala a toolchain e aquece o cache de módulos/build.
O job de teste compila todos os pacotes (./...) sob a raiz do módulo.
A verificação Tidy garante que os go.mod / go.sum commitados correspondam aos imports.
Jobs opcionais publicam tags, binários ou índices de módulos.

Gatilhos de Fluxo de Trabalho

Gatilho	Uso Típico
`pull_request`	Validar merges para o trunk
`push` para `main`	Validação pós-merge + release
`push` tags `v*`	Artefatos de release ou testes de fumaça de proxy
`workflow_dispatch`	Reconstrução manual ou pipeline de hotfix

Módulos Privados

env:
  GOPRIVATE: github.com/myorg/*
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version-file: go.mod
  - run: git config --global url."https://${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
    if: env.GOPRIVATE != ''

Use um PAT com escopo restrito ou um token de App do GitHub legível apenas por dependências privadas.

Documente o mesmo prefixo GOPRIVATE para desenvolvedores localmente.

Esboço do Job de Release

  release:
    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go test ./...
      - run: goreleaser release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

O push de tag dispara o build após a aprovação dos testes; goreleaser é opcional, mas comum para binários Go.

Filtros de Caminho de Monorepo

on:
  pull_request:
    paths:
      - '**.go'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'

Pule jobs de documentação quando nenhum caminho que impacta o módulo mudar, mas nunca pule quando go.mod mudar.

Armadilhas

Fixar um patch antigo do Go na CI enquanto go.mod diz 1.26 - Erros de incompatibilidade da toolchain. Correção: use go-version-file: go.mod ou patch explícito correspondente.
Falta de verificação tidy - O trunk acumula dependências órfãs. Correção: sempre go mod tidy && git diff --exit-code.
Cache sem chave go.sum - Cache de módulo obsoleto após atualizações de dependência. Correção: inclua go.sum em cache-dependency-path.
GOPRIVATE excessivamente amplo - Ignora acidentalmente o sumdb para módulos públicos. Correção: escopo apenas para prefixos de organização.
Executar testes sem -count=1 - Cache em nível de pacote instável esconde falhas. Correção: use -count=1 na CI ou etapa de limpeza do cache de teste.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
GitLab CI / CircleCI	O padrão da organização não é GitHub	Você já padronizou o Actions para Go
Matriz completa de race/nightly	Cobertura profunda de concorrência	Todo PR (muito lento)
Runners auto-hospedados	Hardware personalizado, air-gapped	Biblioteca pública simples
Apenas hooks de pre-commit	Feedback local rápido	Você precisa de portões impostos no lado do servidor

FAQs

A CI deve usar a mesma versão do Go que a produção?

A CI deve atender ou exceder a diretiva go em go.mod.

A versão de runtime de produção é separada da toolchain usada para compilar.

Como executar testes com o detector de race?

Adicione um job: go test -race ./... em Linux de 64 bits.

Mais lento; geralmente noturno ou apenas para main para economizar tempo de PR.

Preciso de um job separado por módulo em monorepos?

Use matrix sobre diretórios de módulos ou um job da raiz do repositório com go work na CI.

Valide com GOWORK=off antes das tags de release.

Como cachear módulos no Actions?

actions/setup-go com cache: true usa hashes de go.sum.

Para workspaces, liste todos os go.sum em cache-dependency-path.

O lint deve falhar em avisos?

Escolha da equipe.

Comece apenas com erros; aperte à medida que a dívida diminui.

Como testar releases de tags na CI?

Dispare o fluxo de trabalho em push: tags: ['v*'], execute o teste completo e, em seguida, anexe artefatos ou execute goreleaser.

Quais permissões a CI precisa?

contents: read para jobs de teste.

Escrever ou id-token apenas para jobs de release, assinatura ou implantação.

Os fluxos de trabalho podem atualizar go.mod automaticamente?

Possível com bots, mas a revisão é essencial.

PRs tidy cegos podem esconder dependências transitivas maliciosas.

Quanto tempo a CI deve levar?

Menos de 10 minutos para um PR mediano mantém o fluxo do trunk saudável.

Divida lint/matrix se for mais longo; use filtros de caminho com cuidado.

Os testes de integração devem acessar serviços reais?

Use contêineres de serviço ou fluxos de trabalho dedicados.

Mantenha o job de PR padrão hermético com go test -short onde aplicável.

Como alinhar a versão Go do fluxo de trabalho com GOTOOLCHAIN?

Defina GOTOOLCHAIN: local ou auto explicitamente em env para evitar downloads inesperados na CI.

Os PRs de fork precisam de tratamento especial?

Use pull_request com permissões somente leitura padrão de GITHUB_TOKEN.

Evite passar segredos para fluxos de trabalho de fork não confiáveis sem portões de aprovação.

Relacionado

Estratégias de Branching & Fluxo Baseado em Trunk - Portões de CI esperados pelo trunk
Tags Assinadas & Releases de Módulos Go - Pipelines de release acionados por tags
Revisão de Código com PRs do GitHub - O que os revisores esperam de CI verde
Padrões Git de Monorepo com go work - Caminhos de fluxo de trabalho multi-módulo
Melhores Práticas de Git & GitHub - Hábitos de Git e CI em toda a equipe

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizadores - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

Fluxos de trabalho bem projetados armazenam módulos em cache, fixam versões do Go e validam merges antes que alterações ruins no go.mod cheguem ao trunk.

Resumo

Um fluxo de trabalho mínimo de Go CI configura o Go, baixa módulos com cache, executa testes e vet, e falha se go mod tidy alterasse arquivos.

Adicione golangci-lint, detecção de race e jobs de release que criam tags semver quando os mantenedores precisam de automação.

Mantenha segredos com escopo para busca de dependências privadas GOPRIVATE e credenciais de publicação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.26.x'
          cache: true
      - run: go test ./...
      - run: go vet ./...
      - run: go mod tidy && git diff --exit-code go.mod go.sum

Quando usar isso:

Novo repositório de módulo Go precisando de verificações de PR antes do merge.
Substituindo a cultura ad hoc de go test apenas local.
Adicionando automação de release após desvios manuais de git tag.
Aplicando grafos de módulos organizados em monorepos com filtros de caminho.

Exemplo de Trabalho

CI completa mais job de lint para github.com/myorg/widget:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
 
permissions:
  contents: read
 
env:
  GOTOOLCHAIN: local
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache-dependency-path: |
            go.sum
            **/go.sum
 
      - name: Test
        run: go test -count=1 ./...
 
      - name: Vet
        run: go vet ./...
 
      - name: Verificação Mod tidy
        run: go mod tidy && git diff --exit-code go.mod go.sum
 
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest

O que isso demonstra:

go-version-file: go.mod alinha a CI com o nível da toolchain declarado no módulo.
Caminhos de cache incluem arquivos go.sum aninhados para repositórios multi-módulo.
Job de lint separado mantém o feedback paralelo sem bloquear o início dos testes.

Análise Detalhada

Como Funciona

actions/checkout clona a referência de merge do PR ou o SHA do push.
setup-go instala a toolchain e aquece o cache de módulos/build.
O job de teste compila todos os pacotes (./...) sob a raiz do módulo.
A verificação Tidy garante que os go.mod / go.sum commitados correspondam aos imports.
Jobs opcionais publicam tags, binários ou índices de módulos.

Gatilhos de Fluxo de Trabalho

Gatilho	Uso Típico
`pull_request`	Validar merges para o trunk
`push` para `main`	Validação pós-merge + release
`push` tags `v*`	Artefatos de release ou testes de fumaça de proxy
`workflow_dispatch`	Reconstrução manual ou pipeline de hotfix

Módulos Privados

env:
  GOPRIVATE: github.com/myorg/*
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version-file: go.mod
  - run: git config --global url."https://${{ secrets.GH_PAT }}@github.com/".insteadOf "https://github.com/"
    if: env.GOPRIVATE != ''

Use um PAT com escopo restrito ou um token de App do GitHub legível apenas por dependências privadas.

Documente o mesmo prefixo GOPRIVATE para desenvolvedores localmente.

Esboço do Job de Release

  release:
    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go test ./...
      - run: goreleaser release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

O push de tag dispara o build após a aprovação dos testes; goreleaser é opcional, mas comum para binários Go.

Filtros de Caminho de Monorepo

on:
  pull_request:
    paths:
      - '**.go'
      - 'go.mod'
      - 'go.sum'
      - '.github/workflows/**'

Pule jobs de documentação quando nenhum caminho que impacta o módulo mudar, mas nunca pule quando go.mod mudar.

Armadilhas

Fixar um patch antigo do Go na CI enquanto go.mod diz 1.26 - Erros de incompatibilidade da toolchain. Correção: use go-version-file: go.mod ou patch explícito correspondente.
Falta de verificação tidy - O trunk acumula dependências órfãs. Correção: sempre go mod tidy && git diff --exit-code.
Cache sem chave go.sum - Cache de módulo obsoleto após atualizações de dependência. Correção: inclua go.sum em cache-dependency-path.
GOPRIVATE excessivamente amplo - Ignora acidentalmente o sumdb para módulos públicos. Correção: escopo apenas para prefixos de organização.
Executar testes sem -count=1 - Cache em nível de pacote instável esconde falhas. Correção: use -count=1 na CI ou etapa de limpeza do cache de teste.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
GitLab CI / CircleCI	O padrão da organização não é GitHub	Você já padronizou o Actions para Go
Matriz completa de race/nightly	Cobertura profunda de concorrência	Todo PR (muito lento)
Runners auto-hospedados	Hardware personalizado, air-gapped	Biblioteca pública simples
Apenas hooks de pre-commit	Feedback local rápido	Você precisa de portões impostos no lado do servidor

FAQs

A CI deve usar a mesma versão do Go que a produção?

A CI deve atender ou exceder a diretiva go em go.mod.

A versão de runtime de produção é separada da toolchain usada para compilar.

Como executar testes com o detector de race?

Adicione um job: go test -race ./... em Linux de 64 bits.

Mais lento; geralmente noturno ou apenas para main para economizar tempo de PR.

Preciso de um job separado por módulo em monorepos?

Use matrix sobre diretórios de módulos ou um job da raiz do repositório com go work na CI.

Valide com GOWORK=off antes das tags de release.

Como cachear módulos no Actions?

actions/setup-go com cache: true usa hashes de go.sum.

Para workspaces, liste todos os go.sum em cache-dependency-path.

O lint deve falhar em avisos?

Escolha da equipe.

Comece apenas com erros; aperte à medida que a dívida diminui.

Como testar releases de tags na CI?

Dispare o fluxo de trabalho em push: tags: ['v*'], execute o teste completo e, em seguida, anexe artefatos ou execute goreleaser.

Quais permissões a CI precisa?

contents: read para jobs de teste.

Escrever ou id-token apenas para jobs de release, assinatura ou implantação.

Os fluxos de trabalho podem atualizar go.mod automaticamente?

Possível com bots, mas a revisão é essencial.

PRs tidy cegos podem esconder dependências transitivas maliciosas.

Quanto tempo a CI deve levar?

Menos de 10 minutos para um PR mediano mantém o fluxo do trunk saudável.

Divida lint/matrix se for mais longo; use filtros de caminho com cuidado.

Os testes de integração devem acessar serviços reais?

Use contêineres de serviço ou fluxos de trabalho dedicados.

Mantenha o job de PR padrão hermético com go test -short onde aplicável.

Como alinhar a versão Go do fluxo de trabalho com GOTOOLCHAIN?

Defina GOTOOLCHAIN: local ou auto explicitamente em env para evitar downloads inesperados na CI.

Os PRs de fork precisam de tratamento especial?

Use pull_request com permissões somente leitura padrão de GITHUB_TOKEN.

Evite passar segredos para fluxos de trabalho de fork não confiáveis sem portões de aprovação.

Relacionado

Estratégias de Branching & Fluxo Baseado em Trunk - Portões de CI esperados pelo trunk
Tags Assinadas & Releases de Módulos Go - Pipelines de release acionados por tags
Revisão de Código com PRs do GitHub - O que os revisores esperam de CI verde
Padrões Git de Monorepo com go work - Caminhos de fluxo de trabalho multi-módulo
Melhores Práticas de Git & GitHub - Hábitos de Git e CI em toda a equipe

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizadores - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

GitHub Actions para Repositórios Go

Buscar na documentação

GitHub Actions para Repositórios Go