SkillsApr 13, 2026·3 min read

GoReleaser — Release Engineering for Go Projects

GoReleaser automates the entire Go release process: cross-compilation for all platforms, Docker image building, Homebrew formula generation, changelog creation, and publishing to GitHub/GitLab releases — all from a single YAML config.

Script Depot · Community

Agent ready

Safe staging for this asset

This asset is staged first. The copied prompt tells the agent to inspect the staged files and ask before activating scripts, MCP config, or global config.

Stage only · 29/100Policy: stage

Agent surface

Any MCP/CLI agent

Kind

Skill

Install

Stage only

Trust

Trust: Established

Entrypoint

step-1.md

Safe staging command

npx -y tokrepo@latest install 10f0b18f-373d-11f1-9bc6-00163e2b0d79 --target codex

Stages files first; activation requires review of the staged README and plan.

TL;DR

GoReleaser cross-compiles, packages, and publishes Go binaries from a single YAML config and one command.

§01

What it is

GoReleaser is an open-source tool that automates the full release pipeline for 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 and Scoop formulas, publishes to GitHub or GitLab Releases, and generates changelogs.

GoReleaser targets Go developers and teams who want repeatable, automated releases without writing custom shell scripts or CI pipeline steps for each artifact type.

§02

How it saves time or tokens

Without GoReleaser, releasing a Go project to multiple platforms requires separate build scripts, archive commands, Docker builds, and package manager formula generators. GoReleaser replaces all of this with a single YAML config file. The snapshot mode lets you test the entire pipeline locally before tagging a real release, catching issues before they hit CI.

§03

How to use

Install GoReleaser:

brew install goreleaser

Initialize the config in your project root:

goreleaser init

Test locally without publishing:

goreleaser release --snapshot --clean

Tag and release:

export GITHUB_TOKEN=ghp_xxx
git tag v1.0.0
git push origin v1.0.0
goreleaser release --clean

§04

Example

A .goreleaser.yaml that builds for multiple platforms and creates a Homebrew tap:

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64

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

brews:
  - repository:
      owner: myorg
      name: homebrew-tap
    homepage: https://github.com/myorg/myproject
    description: My Go project

changelogs:
  sort: asc
  filters:
    exclude:
      - '^docs:'
      - '^test:'

§05

Related on TokRepo

DevOps automation tools — CI/CD and release automation
Coding tools — developer productivity tooling

§06

Common pitfalls

Forgetting to set CGO_ENABLED=0 for cross-compilation; CGo dependencies break builds on non-native platforms
Not testing with --snapshot before tagging; a failed release after git push --tags requires manual cleanup on GitHub
Using GoReleaser Pro features in the open-source version; check the docs for which features require a license

Frequently Asked Questions

Does GoReleaser work with GitLab?+

Yes. GoReleaser supports GitHub, GitLab, and Gitea as release targets. You configure the provider in .goreleaser.yaml and set the corresponding token environment variable (GITLAB_TOKEN for GitLab).

Can GoReleaser build Docker images?+

Yes. GoReleaser has a dockers section in the config that builds and pushes Docker images as part of the release. It supports multi-platform images via buildx and can push to any container registry.

What is the difference between GoReleaser OSS and Pro?+

GoReleaser OSS is free and covers most release needs. GoReleaser Pro adds features like monorepo support, custom publishers, nightly builds, and Homebrew caveats. The OSS version handles the majority of single-repo Go projects.

How does GoReleaser handle changelogs?+

GoReleaser generates changelogs from git commit messages between the current and previous tags. You can filter commits by prefix (e.g., exclude docs: and test: commits), group them by type, and customize the format in the config.

Can I use GoReleaser in GitHub Actions?+

Yes. GoReleaser provides an official GitHub Action (goreleaser/goreleaser-action) that handles installation and execution. You trigger it on tag push events and pass GITHUB_TOKEN for publishing permissions.

Citations (3)

GoReleaser GitHub— GoReleaser automates Go release pipelines
GoReleaser Docs— GoReleaser supports GitHub Actions for CI integration
Go Documentation— Cross-compilation with CGO_ENABLED=0 for Go

Related on TokRepo

DevOps tools Coding tools Automation tools

Discussion

No comments yet. Be the first to share your thoughts.

Related Assets

Release Please — Automated Releases Based on Conventional Commits

Release Please generates release pull requests and changelogs from Conventional Commit messages, automating semantic versioning and publishing for GitHub repositories.

Skills

Script Depot

semantic-release — Fully Automated Version Management and Publishing

semantic-release automates the entire package release workflow by analyzing commit messages to determine version bumps, generating changelogs, and publishing to package registries.

Skills

AI Open Source

release-it — Automated Versioning and Package Publishing

A CLI tool that automates version bumping, changelog generation, Git tagging, and publishing to npm or GitHub Releases with interactive or CI-driven workflows.

Skills

AI Open Source

Waypoint — Build, Deploy & Release Applications with a Single Workflow

HashiCorp Waypoint provides a consistent developer workflow for building, deploying, and releasing applications across Kubernetes, ECS, Nomad, and other platforms.

Skills

Script Depot