GitHub Actions for Go Repos

GitHub Actions runs the same go test, lint, and module hygiene checks on every push and pull request.

Well-designed workflows cache modules, pin Go versions, and gate merges before bad go.mod changes reach trunk.

Summary

A minimal Go CI workflow sets up Go, downloads modules with caching, runs tests and vet, and fails if go mod tidy would change files.

Add golangci-lint, race detection, and release jobs that create semver tags when maintainers need automation.

Keep secrets scoped to GOPRIVATE module fetch and publishing credentials.

Recipe

Quick-reference recipe card - copy-paste ready.

# .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

When to reach for this:

• New Go module repo needing PR checks before merge.
• Replacing ad hoc local-only go test culture.
• Adding release automation after manual git tag drift.
• Enforcing tidy module graphs on monorepos with path filters.

Working Example

Complete CI plus lint job for 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: Mod tidy check
        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

What this demonstrates:

• go-version-file: go.mod aligns CI with the module's declared toolchain floor.
• Cache paths include nested go.sum files for multi-module repos.
• Separate lint job keeps feedback parallel without blocking test startup.

Deep Dive

How It Works

1. actions/checkout clones the PR merge ref or push SHA.
2. setup-go installs the toolchain and warms module/build cache.
3. Test job compiles all packages (./...) under the module root.
4. Tidy check ensures committed go.mod / go.sum match imports.
5. Optional jobs publish tags, binaries, or module indexes.

Workflow Triggers

Private Modules

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 a fine-scoped PAT or GitHub App token readable only by private deps.

Document the same GOPRIVATE prefix for developers locally.

Release Job Sketch

  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 }}

Tag push triggers build after tests pass; goreleaser is optional but common for Go binaries.

Monorepo Path Filters

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

Skip doc-only jobs when no module-impacting paths change, but never skip when go.mod changes.

Gotchas

• Pinning an old Go patch in CI while go.mod says 1.26 - Toolchain mismatch errors. Fix: use go-version-file: go.mod or explicit matching patch.
• Missing tidy check - Trunk accumulates orphan requires. Fix: always go mod tidy && git diff --exit-code.
• Caching without go.sum key - Stale module cache after dependency bumps. Fix: include go.sum in cache-dependency-path.
• Overbroad GOPRIVATE - Accidentally bypasses sumdb for public modules. Fix: scope to org prefixes only.
• Running tests without -count=1 - Flaky package-level cache hides failures. Fix: use -count=1 in CI or clean test cache step.

Alternatives

FAQs

Related

• Branching Strategies & Trunk-Based Flow - CI gates trunk expects
• Signed Tags & Go Module Releases - Tag-triggered release pipelines
• Code Review with GitHub PRs - What reviewers expect from green CI
• Monorepo Git Patterns with go work - Multi-module workflow paths
• Git & GitHub Best Practices - Team-wide Git and CI habits

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).