agentleFS
mazreanmazrean/agent-skills/skills/releasing-zig-with-goreleaser/SKILL.md

releasing-zig-with-goreleaser

Skill2 starsChanged 8 months agoMITView on GitHub

Releases Zig CLI applications using GoReleaser v2.5+. Use when setting up automated releases for Zig projects, configuring .goreleaser.yaml for Zig builds, creating GitHub Actions CI/CD for Zig releases, or publishing Zig binaries via Homebrew, Docker, or Linux packages.

  • Reads credentials
  • Installs packages
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When targets is omitted, GoReleaser builds for:

    line 115
  2. Distinctive:

    Create fat binaries combining x86_64 and aarch64:

    line 135
  3. Very specific:

    GoReleaser does not install Zig: - ensure Zig is available in CI via mlugg/setup-zig

    line 192
  4. Very specific:

    Config validation: - always run goreleaser check before pushing

    line 193
  5. Very specific:

    Snapshot mode: - use --snapshot for local testing without publishing

    line 194

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Releasing Zig with GoReleaser

Set up automated cross-platform releases for Zig CLI applications using GoReleaser v2.5+. Covers build configuration, GitHub Actions, packaging (Homebrew, Docker, deb/rpm), signing, and SBOMs.

Use this skill when configuring GoReleaser for a Zig project, setting up release automation CI/CD, or publishing Zig binaries to multiple platforms.

Supporting files: GORELEASER-CONFIG.md for full configuration reference, GITHUB-ACTIONS.md for CI/CD workflow setup, PACKAGING.md for Homebrew, Docker, and Linux package distribution.

Quick Start

Prerequisites

  • GoReleaser v2.5+ (go install github.com/goreleaser/goreleaser/v2@latest)
  • Zig compiler installed
  • A Zig project that builds with zig build

Initialize

goreleaser init

This generates .goreleaser.yaml with Zig-aware defaults if a build.zig is detected.

Minimal .goreleaser.yaml

version: 2

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

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

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

build.zig Requirements

GoReleaser invokes zig build with target flags. Your build.zig must accept standard target options:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "my-cli",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    b.installArtifact(exe);
}

Test Locally

# Validate config
goreleaser check

# Build without publishing
goreleaser release --clean --snapshot

Build Configuration

Builder Options

builds:
  - id: my-app
    builder: zig
    binary: my-app          # Output binary name
    dir: .                  # Working directory
    tool: zig               # Zig binary path (default: "zig")
    command: build           # Build command (default: "build")
    flags:
      - --release            # Zig build flags
    env:
      - CGO_ENABLED=0
    hooks:
      pre: ./scripts/pre-build.sh
      post: ./scripts/post-build.sh {{ .Path }}

Default Targets

When targets is omitted, GoReleaser builds for:

  • x86_64-linux
  • x86_64-macos
  • x86_64-windows
  • aarch64-linux
  • aarch64-macos

Template Variables

GoReleaser translates Zig target pairs to GOOS/GOARCH for template compatibility:

TemplateDescription
{{ .Os }}GOOS equivalent (linux, darwin, windows)
{{ .Arch }}GOARCH equivalent (amd64, arm64)
{{ .Target }}Original Zig target (e.g., x86_64-linux)
{{ .Abi }}ABI part of target (e.g., gnu, musl)

Universal Binaries (macOS)

Create fat binaries combining x86_64 and aarch64:

universal_binaries:
  - replace: true

GitHub Actions Workflow

Minimal workflow for automated releases on tag push:

name: release

on:
  push:
    tags:
      - "v*"

permissions:
  contents: write

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: mlugg/setup-zig@v1

      - uses: goreleaser/goreleaser-action@v6
        with:
          distribution: goreleaser
          version: "~> v2"
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

See GITHUB-ACTIONS.md for advanced workflows with signing, Docker, and Homebrew.

Release Workflow

# 1. Tag the release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# 2. GitHub Actions runs goreleaser automatically
# Or manually:
goreleaser release --clean

Key Points

  1. GoReleaser does not install Zig - ensure Zig is available in CI via mlugg/setup-zig
  2. Config validation - always run goreleaser check before pushing
  3. Snapshot mode - use --snapshot for local testing without publishing
  4. Flags template support - flags, env, tool, and hooks all support Go templates

See GORELEASER-CONFIG.md for the full configuration reference including signing, SBOMs, and advanced archive options.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.