crystalreleaser
crystalreleaser
Release automation for Crystal projects, in the spirit of GoReleaser. From a git tag, crystalreleaser:
- builds the binaries of several platforms (natively, in docker, or by cross-compilation);
- packs them into reproducible
.tar.gz/.ziparchives; - writes
checksums.txtand a changelog from the commits since the last tag; - publishes a GitHub release with every asset;
- produces
.deband.rpmpackages, a Homebrew formula and an aqua registry entry.
It is a single executable with no runtime dependency, static on Linux and linked only against the libraries macOS ships on macOS: tar, zip, ar, cpio and the RPM format are written natively, without nfpm, dpkg-deb or rpmbuild. Zip archives keep the Unix permissions, so an extracted binary is still executable.
Installation
From a release (Linux binaries are static), once one is published:
- the archives,
.deband.rpmof the GitHub release page; - Homebrew:
brew install jbox-web/tap/crystalreleaser; - aqua, with the jbox-web registry configured: package
jbox-web/crystalreleaser.
From source (Crystal >= 1.20):
git clone https://github.com/jbox-web/crystalreleaser && cd crystalreleaser
mise dev:build # bin/crystalreleaser
Quickstart
crystalreleaser init # .crystalreleaser.yml from shard.yml
crystalreleaser check # validate it
crystalreleaser release --snapshot --skip=publish # try everything locally, in dist/
git tag v1.0.0 && git push --tags
GITHUB_TOKEN=... crystalreleaser release # the real thing
Commands:
crystalreleaser init generate a commented .crystalreleaser.yml from shard.yml
crystalreleaser check load and validate the configuration, print the warnings
crystalreleaser build [--snapshot] [--split] [--os X] [--arch Y] [--id ID] [--clean] [--parallelism N]
crystalreleaser release [--snapshot] [--merge] [--allow-missing] [--skip=a,b] [--clean]
[--release-notes FILE] [--parallelism N]
crystalreleaser changelog print the changelog the next release would carry
crystalreleaser licenses print the third-party notices embedded in the binary
crystalreleaser --version
Global options: -f/--config FILE (default: .crystalreleaser.yml, then .crystalreleaser.yaml, then crystalreleaser.yml), --verbose (debug lines, backtraces on error), --quiet (warnings and errors only).
Outputs all go to dist/. It must be empty when a run starts: --clean empties it. Add /dist/ to .gitignore, since a release needs a clean tree. Because --clean removes it, dist must be a directory inside the project: the project itself, a parent or an absolute path is refused.
Injecting the version
Crystal has no -ldflags -X. crystalreleaser exports each build's env:, rendered, into the compiler's environment, and the code reads it at compile time with the env macro:
module MyApp
VERSION = {{ env("MYAPP_VERSION") || "dev" }}
end
builds:
- id: myapp
target: myapp
env:
- MYAPP_VERSION={{ .Version }}
- MYAPP_COMMIT={{ .ShortCommit }}
crystalreleaser does this for itself with CRYSTALRELEASER_VERSION. With the docker strategy the variables are passed to the container with -e NAME, their values through the environment of the docker process: they do not appear on its command line.
The three build strategies
| Strategy | What runs | Platforms | Limits |
|---|---|---|---|
native |
crystal build on the host |
the host's own os/arch | Skipped (with a warning) on any other host. static: true needs a musl host (Alpine): glibc cannot be linked statically, and macOS has no static linking at all. |
docker |
crystal build in a Crystal image (84codes/crystal:<version>-alpine by default), with --static when the platform says static: true |
linux/amd64, linux/arm64 | In an Alpine image, set static: true: a dynamic musl binary runs on no glibc distribution (check warns about it). Needs docker; the other architecture runs under QEMU and needs binfmt (docker run --privileged --rm tonistiigi/binfmt --install arm64). Emulated builds run one at a time. |
cross |
crystal build --cross-compile, then zig cc against a sysroot (or, with linker: cc, cc --target when cc is clang and <triple>-gcc when it is gcc) |
any target with a sysroot | The sysroot must hold the target's static libraries (libgc, pcre2, libyaml, openssl...). crystalreleaser does not provide it; it fails if it is missing. |
A musl sysroot for linux/arm64 can be taken from Alpine (verified with zig 0.17.1, crystal 1.20.3, from a macOS arm64 host):
docker run --rm --platform linux/arm64 -v "$PWD/sysroot:/out" alpine:3 sh -c '
apk add musl-dev gc-dev gc-static pcre2-dev pcre2-static yaml-static \
zlib-static openssl-libs-static libevent-static &&
cp -a /lib /out/lib && mkdir -p /out/usr && cp -a /usr/lib /out/usr/lib'
With zig, the sysroot is passed as -L folders only (zig would prefix even absolute paths with --sysroot), and -lunwind is added for linux targets: zig cc does not link the libgcc_eh gcc brings implicitly, which Crystal's exceptions need.
The docker strategy runs as the calling user (dist/ is not left to root), mounts the project at /src, and keeps the compiler cache and lib/ in named volumes: crystalreleaser-cache-<arch>-<project> and crystalreleaser-lib-<arch>-<project>-<build id>, where <project> is a digest of the project path. Two builds, or two projects built at the same time, never share a lib/. Mounting that volume leaves an empty lib/ in the project when it had none.
After each build, file (when installed) checks the architecture and, when asked, the static linking; a mismatch is a warning.
Split / merge: building darwin and linux in one release
No machine builds everything: darwin needs a macOS runner. Split the release:
- on each runner,
crystalreleaser build --splitbuilds what that host can (or exactly--os/--arch) intodist/<os>_<arch>/, with a partialartifacts.json; - a final job gathers the
dist/folders and runscrystalreleaser release --merge: it checks that every configured platform is there, all from the same commit (--allow-missingturns a missing platform into a warning), then archives, checksums and publishes without compiling.
docs/github-actions.md has a complete workflow; crystalreleaser's own release workflow uses it.
Pipeline
validate → shard → git → before → build → archive → nfpm → checksum → changelog → metadata → homebrew → aqua → release → homebrew (push) → aqua (push)
The formula and the registry entry are generated before the release is published, so that what cannot be generated fails while nothing is public yet; they are pushed once it is.
--skip=name,...skips pipes by name;publishskips the GitHub release and the pushes of the formula and the registry entry (which are still generated indist/homebrew/anddist/aqua/).releaseskips the GitHub release and, with it, those pushes: the files would point at assets that are not there.validate,git,buildandmergecannot be skipped: a run means nothing without them.--snapshotreleases an untagged, possibly dirty tree as<next patch>-SNAPSHOT-<commit>and never publishes.- Without
--snapshot, the tree must be clean and HEAD must carry exactly one semver tag.GITHUB_TOKEN(orGH_TOKEN), the tokens of the tap and of the registry, and--release-notesare checked before any build. In a split release they are only checked byrelease --merge, once every runner has built:build --splitpublishes nothing and asks for no token. A shallow clone is refused: the previous tag and the changelog need the history (fetch-depth: 0with actions/checkout). A snapshot on a shallow clone is built, with a warning when no tag is in reach: its version then starts from 0.0.0. - The GitHub release is created as a draft and published once every asset is uploaded: a run that fails halfway leaves no public release with missing files, and running it again resumes that draft, skipping the assets already there with the same sha256. With
release.draft: trueit stays a draft, and the formula and the registry entry are written but not pushed, since their URLs only answer once the release is published. dist/artifacts.jsonlists the binaries, archives, packages and checksums with their sha256 (not the formula nor the registry entry, written after it);dist/metadata.jsonholds the release facts.
Configuration
Every top-level key is optional, and so is nearly everything under them: an entry that is written must give platforms[].os and arch, nfpms[].maintainer, aqua[].repository and aqua[].path. Without a config file, each target of shard.yml is built natively for the host and archived.
version: 1
project_name: myapp # default: shard.yml name
dist: dist # a directory inside the project
env: # exported to builds and hooks, templated
- FOO=bar
before:
hooks: # shell commands, templated
- shards install --production
builds:
- id: myapp # default: target
target: myapp # shard.yml target; main is deduced
# main: src/myapp.cr # or explicit
binary: myapp # default: target
flags: [--release, --no-debug] # default: [--release]
env:
- MYAPP_VERSION={{ .Version }}
platforms: # default: the host, native
- { os: linux, arch: amd64, strategy: docker, static: true }
- { os: linux, arch: arm64, strategy: docker, static: true }
- { os: darwin, arch: arm64, strategy: native }
docker:
image: 84codes/crystal:{{ .CrystalVersion }}-alpine
platform_flag: true # pass --platform linux/<arch>
shards_install: true
cross:
linker: zig # zig | cc
sysroot: /opt/sysroots/{{ .Os }}-{{ .Arch }}
link_flags: []
archives:
- id: default
builds: [myapp] # default: all
formats: [tar.gz] # tar.gz | zip | binary: see below
format_overrides:
- { os: windows, formats: [zip] }
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
wrap_in_directory: false
files: # default: LICENSE*, README*, CHANGELOG*
- LICENSE
- src: completions/*
dst: completions
checksum:
name_template: checksums.txt
algorithm: sha256
split: false # true: one <asset>.sha256 per asset
changelog:
use: git
sort: asc # asc | desc
filters:
exclude: ["^docs:", "Merge pull request"]
groups:
- { title: Features, regexp: '^feat(\(.+\))?!?:' }
- { title: Others } # catch-all, last
release:
github: { owner: me, name: myapp } # default: the origin remote
draft: false
prerelease: auto # auto: semver pre-release => prerelease
replace_existing_artifacts: false
make_latest: "true" # true | false | legacy: see below
name_template: "{{ .Tag }}"
header: ""
footer: ""
nfpms:
- id: packages
builds: [myapp]
package_name: myapp
formats: [deb, rpm]
vendor: me
homepage: https://example.com
maintainer: Me <me@example.com> # required
description: One line summary
license: MIT
section: utils # deb
priority: optional # deb
bindir: /usr/bin
contents:
- { src: LICENSE, dst: /usr/share/doc/myapp/LICENSE }
- { src: myapp.conf, dst: /etc/myapp/myapp.conf, type: config } # see below
dependencies: ["ca-certificates", "libfoo >= 1.2"] # see below
file_name_template: "{{ .PackageName }}_{{ .Version }}_{{ .Arch }}"
brews:
- name: myapp
repository: { owner: me, name: homebrew-tap, branch: master, token: "{{ .Env.HOMEBREW_TAP_TOKEN }}" }
directory: Formula
homepage: https://example.com
description: One line summary
license: MIT
install: | # default: bin.install "<name>"
bin.install "myapp"
test: | # default: system "#{bin}/<name>", "--version"
system "#{bin}/myapp", "--version"
skip_upload: "false" # false | true | auto: see below
aqua:
- repository: { owner: me, name: aqua-registry, branch: master, token: "{{ .Env.AQUA_REGISTRY_TOKEN }}" }
path: pkgs/me/myapp/registry.yaml
description: One line summary
skip_upload: "false"
crystalreleaser check validates all of it statically: unknown and repeated keys, unique ids, references between sections, os/arch couples (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, freebsd/amd64; windows is accepted but not built yet), a static native build on a host that cannot link it, dist, the install paths of packages (absolute, without ..), regular expressions, and the variables each template uses.
Templates
{{ .Name }}, {{ .Env.NAME }}, and the filters upper, lower, replace "a" "b", trimprefix "v", trimsuffix "x", shellquote: {{ .Tag | trimprefix "v" | upper }}. A quoted string is written as it is, which is how a literal brace pair is obtained: {{ "{{" }}.Id{{ "}}" }}.
Values are inserted as they are. In a before.hooks command, which a shell runs, pass anything that comes from git or from the environment through shellquote: echo {{ .Branch | shellquote }}. Hooks are logged as written in the config, never with the values they rendered.
| Variable | Value |
|---|---|
ProjectName |
project name |
Version |
tag without v: 1.2.3-rc.1 |
RawVersion |
1.2.3 |
Tag, PreviousTag |
v1.2.3-rc.1, v1.2.2 |
Major, Minor, Patch, Prerelease |
1, 2, 3, rc.1 |
Commit, ShortCommit, Branch |
git HEAD |
Date, Timestamp |
run time, RFC 3339 UTC and Unix |
CrystalVersion |
the host's crystal version |
IsSnapshot |
true / false |
Os, Arch, Target, Binary |
per platform (builds, archives, packages) |
PackageName |
in nfpms |
An unknown variable, or one a field cannot provide, is an error naming the field.
Packages, formula, registry
- dependencies: one list for both formats,
nameorname >= 1.2(operators<,<=,=,>=,>; Debian'sname (>= 1.2)is read too). Each format gets its own syntax:name (>= 1.2)in a .deb, with<<and>>for the strict comparisons. - .deb:
debian-binary,control.tar.gz(control withInstalled-Size, md5sums),data.tar.gzwith every parent directory listed. - .rpm: lead, signature header (SHA1/SHA256 of the header, MD5 and size of header + payload), header with the payload SHA256 that rpm >= 4.14 checks, gzip-compressed cpio payload. The package owns the directories only it creates (
/usr/share/doc/<name>), so removing it removes them; system directories (/usr/bin) are left alone. No GPG signature: rpm 6 (Fedora 43 and later) refuses unsigned packages unless installed withrpm -i --nosignature. A pre-release version1.2.3-rc.1becomes1.2.3~rc.1in both formats. - formats,
binary: the binary itself is the asset, with no archive around it and no extension, for the projects whose users download one file and run it. Thefiles:are left out, and each platform must have one binary only. A name template without the version gives stable names:name_template: "{{ .ProjectName }}-{{ .Os }}-{{ .Arch }}"publishesmyapp-linux-amd64. The Homebrew formula and the aqua entry only ever describe the tar.gz archives. - checksum,
split: one<asset>.sha256next to each asset, in the format ofsha256sum, instead of the singlechecksums.txt; the aqua entry then points at{{.Asset}}.sha256. - make_latest:
true(default, and what GitHub does when told nothing) marks the release "Latest" when it is published, whatever its version: av1.9.1published afterv2.0.0takes the label.legacylets GitHub pick by version,falsenever marks it. A pre-release is never "Latest". - contents,
type: without it a file is an ordinary one, replaced on every upgrade.type: configmakes it a configuration file, which an upgrade does not silently overwrite once it was edited: dpkg asks (or keeps it), rpm saves the edited file as.rpmsave.type: config|noreplaceis the same for dpkg; rpm then keeps the edited file and installs the new one as.rpmnew. - Homebrew:
on_macos/on_linux×on_intel/on_armblocks pointing at the tar.gz assets of the release. - aqua: a
github_releasepackage whoseassettemplate andsupported_envsare derived from the archives actually produced. - skip_upload, on a
brewsor anaquaentry:false(default) pushes the file on every release,trueonly writes it indist/, andautodoes not push it for a semver pre-release (v1.2.0-rc.1), so that the users of the tap or the registry only ever get stable versions.
Third-party notices
The static binary embeds the licenses of what it links (openssl, pcre2, libyaml, zlib, boehm-gc, musl, libgcc, Crystal): crystalreleaser licenses. pcre2, libyaml, zlib and musl come with their own license file, copyright notice included, as their licenses require.
Development
mise dev:deps && mise dev:spec # specs (no network)
mise dev:spec -- --tag docker # only the docker-tagged examples
# only the cross-compilation examples: zig, and the sysroot built above
MISE_ZIG_VERSION=0.17.1 CRYSTALRELEASER_SYSROOT=$PWD/sysroot mise dev:spec -- --tag cross
CRYSTALRELEASER_SYSROOT=... mise dev:spec -- --tag cross
mise dev:ameba && mise dev:format-check
The specs check the hand-written formats with the system tools when they are installed (tar, cpio, unzip, dpkg-deb, rpm) and are pending otherwise. SPEC_REQUIRE_TOOLS=rpm,dpkg-deb (or all) makes a missing tool a failure.
License
MIT — see LICENSE.
crystalreleaser
- 0
- 0
- 0
- 0
- 0
- about 3 hours ago
- November 17, 2026
MIT License
Tue, 17 Nov 2026 04:40:11 GMT