goxz

GO + X (crossbuild) + Z (zip)

Just do cross building and archiving go tools conventionally

% go install github.com/Songmu/goxz/cmd/goxz@latest

Built binaries are available on gihub releases. https://github.com/Songmu/goxz/releases

You can also install goxz with aqua.

% aqua g -i Songmu/goxz

The action installs and runs goxz, building release archives into goxz:

permissions:
  attestations: read
  contents: read

steps:
- uses: actions/checkout@v7
- uses: actions/setup-go@v6
  with:
    go-version-file: go.mod
- id: goxz
  uses: Songmu/goxz@v0
  with:
    package-version: ${{ github.ref_name }}
    packages: ./cmd/mytool

The project directory, target platforms, archive name, destination, included resources, build flags, static linking, ZIP output, and checksum manifest can be configured:

- uses: Songmu/goxz@v0
  with:
    directory: ./path/to/module
    package-version: v1.2.3
    os: linux,darwin,windows
    arch: amd64,arm64
    name: mytool
    destination: dist
    packages: ./cmd/mytool
    include: NOTICE
    build-ldflags: -s -w
    build-tags: release
    static: true
    zip: true
    checksum: true

The action outputs the absolute directory path as output-dir. The attestations: read permission allows the action to verify the downloaded goxz binary. The contents: read permission is required by the checkout step. The action uses goxz's default trimpath behavior.

goxz creates reproducible ZIP and tar.gz archives when built from the same commit, with the same Go toolchain, dependencies, and build configuration. It uses the target commit timestamp for archive metadata. Set SOURCE_DATE_EPOCH (Unix seconds) to override that timestamp. An invalid SOURCE_DATE_EPOCH causes goxz to exit with an error. If neither timestamp can be resolved, goxz creates archives with its legacy metadata behavior.

Archive entry timestamps, ownership, and modes are normalized. Generated binaries and resources marked executable in the Git index use mode 0755; other files use 0644. -trimpath is enabled by default, but callers must also avoid embedding the current time in linker flags or generated inputs. CGO builds additionally require the same C compiler and libraries.

Use --checksum to generate a SHA256SUMS file alongside the archives:

% goxz --checksum -pv v1.2.3 ./cmd/mytool

The manifest contains SHA-256 hashes for archives generated by the current invocation only. Entries are sorted by archive filename and use the conventional <hash> <filename> format.

Pass a Go text/template value to customize the manifest filename. The template can use .Name and .Version:

% goxz --checksum='{{.Name}}_{{.Version}}_checksums.txt' -pv v1.2.3 ./cmd/mytool

The rendered value must be a non-empty filename in the destination directory; absolute paths and directory separators are rejected. Use --checksum=false to disable checksum generation explicitly. The GitHub Action's checksum input accepts true, false, or the same filename template.

• Simple and Lightweight
• Provides goxc subset
  • only provides cross building and archiving
• No older Go support
• No complicated configuration and behaivors
  • convention over configuration

# in your repository
% goxz -pv 0.0.1 -os=linux,darwin -arch=amd64 ./cmd/mytool [...]

# archives are built into `./goxz` directory by default (configurable by `-d` option)
%  tree ./goxz
goxz/
├── yourapp_0.0.1_darwin_amd64.zip
└── ...

following files are included to archives automatically.

• LICENSE*
• README*
• INSTALL*
• CREDIT*
• CHANGELOG*

You can specify additional resources by using -include option.

{{Package}}_{{Version}}_{{OS}}_{{Arch}}.{{Ext}} or {{Package}}_{{OS}}_{{Arch}}.{{Ext}}

• {{Package}}
  • directory name of the project by default
  • you can specify it with -n option
• {{Version}}
  • When the version is specified by -pv option, that is contained in archive name
• {{Ext}}
  • .zip is by default on "windows" and "darwin", .tar.gz is by default on other os.
  • use -z option to use zip always to compress.
• No file naming notations are available yet
  • ref. goxc: {{.ExeName}}_{{.Version}}_{{.Os}}_{{.Arch}}{{.Ext}}

• -d destination directory (./goxz by default)
• -n application name. by default the directory name is used.
• -os linux,darwin and windows by default
• -arch amd64,arm64 by default
• -pv for speicifing version (optional)
• -o output filename
  • not available with multiple package building
• -z to use zip always to compless
  • by default, zip is used on "windows and "darwin", tar.gz is used on other OS
• -include Include additional resources in archives
• -build-ldflags / -build-tags
• --checksum[=template] generate a SHA-256 checksum manifest
  • --checksum writes SHA256SUMS
  • templates can use .Name and .Version

Songmu