Goreleaser

GoReleaser Skill

GoReleaser automates the release process for software projects. It builds binaries, creates archives, publishes to package managers, builds Docker images, and generates changelogs.

Quick Reference

Essential Commands

# Initialize new config
goreleaser init

# Validate configuration
goreleaser check

# Test build locally (no publish)
goreleaser release --snapshot --clean

# Create release (usually run in CI)
goreleaser release

Configuration File

GoReleaser uses .goreleaser.yaml (or .goreleaser.yml). Enable schema validation:

# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
version: 2

# Project name (defaults to directory name)
project_name: myapp

Minimal Go Configuration

# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
version: 2

builds:
  - main: ./cmd/myapp
    binary: myapp
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    ldflags:
      - -s -w
      - -X main.version={{.Version}}

archives:
  - formats: [tar.gz]
    format_overrides:
      - goos: windows
        formats: [zip]

changelog:
  sort: asc
  filters:
    exclude:
      - "^docs:"
      - "^test:"

Build Targets

Go (default)

builds:
  - builder: go  # optional, default
    main: ./cmd/app
    goos: [linux, darwin, windows]
    goarch: [amd64, arm64]
    goarm: ["6", "7"]  # for ARM builds

Rust

builds:
  - builder: rust
    targets:
      - x86_64-unknown-linux-gnu
      - x86_64-apple-darwin
      - aarch64-apple-darwin

Zig

builds:
  - builder: zig
    targets:
      - x86_64-linux-gnu
      - x86_64-macos
      - aarch64-macos

Prebuilt Binaries

builds:
  - builder: prebuilt
    prebuilt:
      path: dist/myapp_{{ .Os }}_{{ .Arch }}/myapp{{ .Ext }}

Common Patterns

Version Injection (Go)

builds:
  - ldflags:
      - -X main.version={{.Version}}
      - -X main.commit={{.Commit}}
      - -X main.date={{.Date}}

CGO Disabled

builds:
  - env:
      - CGO_ENABLED=0

Multiple Binaries

builds:
  - id: cli
    main: ./cmd/cli
    binary: myapp
  - id: server
    main: ./cmd/server
    binary: myapp-server

Publishing

Homebrew Tap

brews:
  - repository:
      owner: myorg
      name: homebrew-tap
    homepage: https://example.com
    description: "My application"

Docker Images

dockers_v2:
  - dockerfile: Dockerfile
    images:
      - "ghcr.io/myorg/myapp:{{ .Tag }}"
      - "ghcr.io/myorg/myapp:latest"

GitHub Release

release:
  github:
    owner: myorg
    name: myrepo
  draft: false
  prerelease: auto

Environment Variables

Workflow

1. Initialize: goreleaser init creates .goreleaser.yaml
2. Configure: Edit config for your needs (see reference files)
3. Validate: goreleaser check verifies configuration
4. Test: goreleaser release --snapshot --clean tests locally
5. Release: Tag and push, CI runs goreleaser release

release-please Integration Rule

When a project uses both release-please and GoReleaser, always implement them in a unified workflow (same workflow file) instead of separate chained workflows.

Use ../release-please/references/release-please-goreleaser-unified-workflow.md as the canonical integration recipe.

• Run googleapis/release-please-action@v4 first.
• Use its outputs (release_created, tag_name) to conditionally run GoReleaser.
• Checkout ref: ${{ needs.release-please.outputs.tag_name }} before goreleaser release --clean.
• Use GITHUB_TOKEN and avoid introducing a custom PAT just to trigger GoReleaser.

This avoids GitHub Actions token recursion issues and removes the need for release-trigger PAT workarounds.

When to Load References

• Setting up builds: Load references/builds.md for complete build options
• Configuring Docker: Load references/docker.md for multi-arch images
• Linux packages: Load references/nfpm.md for deb/rpm/apk packages
• Package managers: Load references/homebrew.md for Homebrew/Scoop/AUR/etc.
• CI setup: Load references/ci.md for GitHub Actions/GitLab CI
• release-please integration: Load ../release-please/references/release-please-goreleaser-unified-workflow.md for the unified no-custom-PAT workflow
• Template syntax: Load references/templates.md for available variables
• Complete examples: Load references/examples.md for copy-paste configs