Goreleaser

GoReleaser Setup Skill

Automate Go project releases with cross-platform binaries, multi-architecture Docker images, and package distribution.

Overview

GoReleaser handles complete release automation for Go projects:

• Building binaries for multiple OS/architectures
• Creating multi-architecture Docker images and manifests
• Publishing to GitHub/GitLab releases
• Generating Homebrew formulas
• Creating automated changelogs
• Calculating checksums and signatures

This skill provides templates and guidance for professional release automation.

Prerequisites

1. GoReleaser installed: brew install goreleaser or see https://goreleaser.com/install/
2. Docker with buildx: For multi-architecture builds (docker buildx version)
3. Git tags: GoReleaser works with semantic versioning tags (e.g., v1.0.0)
4. GitHub/GitLab token: For release creation and Homebrew tap updates
5. Project structure: Go module with cmd/ directory (or adjust dir field)

Quick Start

Step 1: Analyze Project Structure

Understand your project:

# Check for existing configuration
ls -la .goreleaser.yml .goreleaser.yaml

# Identify build entry point
find . -name "main.go" -type f

# Verify Go module
cat go.mod

Step 2: Copy Template Files

Copy templates from assets/ directory:

# Copy GoReleaser config
cp assets/.goreleaser.yml .

# Copy Dockerfile
cp assets/Dockerfile .

# Copy resources (for Docker)
mkdir -p resources/etc
cp assets/resources/etc/passwd resources/etc/

Step 3: Customize Configuration

Update .goreleaser.yml with project-specific values:

1. Project name: Replace PROJECT_NAME with actual name
2. Build configuration:
   • Set dir if main.go is not in cmd/
   • Adjust ldflags for version injection
   • Configure target OS/architectures
3. Docker registry: Update image templates
   • GitHub: ghcr.io/OWNER/PROJECT
   • GitLab: registry.gitlab.com/OWNER/PROJECT
   • Docker Hub: docker.io/OWNER/PROJECT
4. Homebrew tap (optional): Configure repository and token

Step 4: Update Dockerfile

Customize the Dockerfile:

1. Replace PROJECT_BINARY with actual binary name
2. Adjust user name in both Dockerfile and resources/etc/passwd
3. Add any additional runtime dependencies

Step 5: Set Up CI/CD Integration

Add environment variables to CI/CD:

# GitHub Actions
GITHUB_TOKEN          # Automatic in GitHub Actions
HOMEBREW_TAP_TOKEN    # If publishing to Homebrew

# GitLab CI
GITLAB_TOKEN          # Automatic in GitLab CI
HOMEBREW_TAP_TOKEN    # If publishing to Homebrew

Step 6: Test Configuration

Validate before tagging:

# Check configuration
goreleaser check

# Create snapshot build (no release)
goreleaser build --snapshot --clean

# Test full release process
goreleaser release --snapshot --clean --skip=publish

Step 7: Create Release

When ready:

# Create and push tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# Run GoReleaser (usually in CI/CD)
goreleaser release --clean

Template Files & Patterns

Templates in assets/ directory:

• .goreleaser.yml - Complete config with multi-arch Docker, Homebrew, archives
• Dockerfile - Optimized multi-stage Docker build
• resources/etc/passwd - Non-root container user config

For simpler patterns (binary-only, Docker-only, private registries), see REFERENCE.md.

Task Runner Integration

Integrate with Taskfile.yml:

version: '3'

tasks:
  release:check:
    desc: Validate GoReleaser config
    cmds:
      - goreleaser check

  release:snapshot:
    desc: Test release build
    cmds:
      - goreleaser release --snapshot --clean --skip=publish

  release:
    desc: Create production release
    cmds:
      - goreleaser release --clean

Expected Output

After using this skill, the project will have:

• ✓ .goreleaser.yml configured for the project
• ✓ Dockerfile for multi-architecture builds
• ✓ resources/etc/passwd for non-root container user
• ✓ CI/CD pipeline ready for automated releases
• ✓ Tested snapshot builds

Users can then create releases by simply pushing Git tags.

Additional Documentation

• Configuration patterns and examples: See REFERENCE.md
• Troubleshooting common issues: See TROUBLESHOOTING.md
• Template files: Available in assets/ directory

Best Practices

1. Semantic Versioning: Use v1.2.3 format for tags
2. Conventional Commits: Enables automatic changelog generation
3. Test Snapshots: Always test with --snapshot before tagging
4. Multi-arch Testing: Verify builds work on target architectures
5. Secret Management: Never commit tokens, use CI/CD secrets

Resources

• Official docs: https://goreleaser.com
• Example configs: https://github.com/goreleaser/goreleaser/tree/main/.github/workflows
• Docker buildx: https://docs.docker.com/buildx/working-with-buildx/
• Conventional commits: https://www.conventionalcommits.org/