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/