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

Task	Reference File
Build configuration	references/builds.md
Archives (tar.gz, zip)	references/archives.md
Docker images	references/docker.md
Linux packages (deb/rpm)	references/nfpm.md
Homebrew/Scoop/AUR	references/homebrew.md
Signing & notarization	references/signing.md
Changelog generation	references/changelog.md
CI/CD integration	references/ci.md
release-please integration	../release-please/references/release-please-goreleaser-unified-workflow.md
Template variables	references/templates.md
Complete examples	references/examples.md

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

Variable	Purpose
GITHUB_TOKEN	GitHub API access
GITLAB_TOKEN	GitLab API access
GITEA_TOKEN	Gitea API access
GORELEASER_KEY	Pro license key

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