GoReleaser — Release Engineering for Go Projects

Introduction

GoReleaser takes the pain out of releasing Go projects. A single "goreleaser release" command cross-compiles your binary for Linux, macOS, Windows, and ARM, creates archives, generates checksums, builds Docker images, creates Homebrew formulas, publishes to GitHub Releases, and generates changelogs — all configured in one YAML file.

With over 16,000 GitHub stars, GoReleaser is used by the majority of popular Go projects for their release process. It integrates with GitHub Actions, GitLab CI, and other CI/CD systems.

What GoReleaser Does

GoReleaser orchestrates the complete release pipeline: building binaries for multiple OS/arch combinations, packaging them into archives (tar.gz, zip), generating checksums, building and pushing Docker images, creating Homebrew/Scoop formulas, publishing to GitHub/GitLab releases, and announcing on social media.

Architecture Overview

[git tag v1.0.0]
        |
   [goreleaser release]
        |
+-------+-------+-------+
|       |       |       |
[Build]  [Package] [Publish]
Cross-compile Archives  GitHub Release
linux/amd64  tar.gz    GitLab Release
linux/arm64  zip       Homebrew tap
darwin/amd64 .deb      Scoop bucket
darwin/arm64 .rpm      Docker Hub
windows/amd64 Docker   Snapcraft
        |
   [Changelog]
   Auto-generated from
   git commits/PRs
        |
   [Announce]
   Discord, Slack,
   Twitter, Mastodon

Self-Hosting & Configuration

# .goreleaser.yaml
version: 2
project_name: myapp

builds:
  - env: [CGO_ENABLED=0]
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    ldflags:
      - -s -w -X main.version={{.Version}}

archives:
  - format: tar.gz
    format_overrides:
      - goos: windows
        format: zip
    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

checksum:
  name_template: "checksums.txt"

changelog:
  sort: asc
  filters:
    exclude: ["^docs:", "^test:", "^chore:"]

dockers:
  - image_templates:
      - "ghcr.io/myorg/myapp:{{ .Version }}"
      - "ghcr.io/myorg/myapp:latest"
    dockerfile: Dockerfile

brews:
  - repository:
      owner: myorg
      name: homebrew-tap
    homepage: https://github.com/myorg/myapp
    description: My awesome CLI tool

# GitHub Actions integration
name: Release
on:
  push:
    tags: ["v*"]
jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-go@v5
        with: { go-version: stable }
      - uses: goreleaser/goreleaser-action@v6
        with:
          version: "~> v2"
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Key Features

• Cross-Compilation — build for all OS/arch combinations
• Docker Images — multi-platform Docker image building
• Homebrew/Scoop — auto-generate package manager formulas
• Changelog — auto-generated from git history
• GitHub/GitLab Releases — publish with assets and release notes
• Checksums — SHA256 checksums for all artifacts
• Signing — GPG and cosign artifact signing
• Snapshots — test release locally without publishing

Comparison with Similar Tools

FAQ

Q: Do I need GoReleaser for every Go project? A: GoReleaser is most valuable for CLI tools and applications distributed as binaries. For libraries (imported by other Go code), you only need git tags.

Q: Can I test releases without publishing? A: Yes. Use "goreleaser release --snapshot --clean" to run the full pipeline locally without publishing anything. Great for validating your config.

Q: How do I handle CGO dependencies? A: Cross-compilation with CGO is complex. Use Docker-based builds (goreleaser can build inside Docker) or zig as a C cross-compiler via CGO_CC.

Q: Is GoReleaser free? A: GoReleaser OSS is free and covers most use cases. GoReleaser Pro adds features like monorepo support, custom publishers, and priority support.

Sources

• GitHub: https://github.com/goreleaser/goreleaser
• Documentation: https://goreleaser.com
• Created by Carlos Becker
• License: MIT