Distribution Channels
poof reaches users through several package ecosystems. Every channel is fed by the same signed GitHub release, produced by the Release workflow from a version tag. Where the tooling lives in the repository is covered in the Development Guide.
Cutting a release
Releases are cut by maintainers with two recipes:
just prepare-release <version>generatesCHANGELOG.mdwith git-cliff, bumps the crate version (cargo set-version), updates the Nix flake lockfile, and creates a signed release-preparation commit.just make-release <version>creates the signed annotated tagv<version>onmainand fast-forwards thelatestbranch to it. The pre-push hook runs the tag checks (just pre-push-tag) before the tag reaches GitHub.
GitHub release pipeline
Pushing the tag triggers release.yml
(a manual dispatch builds everything without publishing a release). It:
- checks that the tag matches the version in
Cargo.toml; - builds all 16 targets from
matrix.jsonc(cargoorcross, with cross images resolved and pinned byscripts/release/build_environment.py); - packs each target into a flat
poof-<version>-<target>.tar.gz(binary plusLICENSE.md,README.md,CHANGELOG.md,SECURITY.md) with a per-archive SHA-256, an SPDX SBOM, and a build-environment record; - attests provenance and SBOM for every binary and archive with GitHub artifact attestations, and verifies them inside the workflow;
- signs the combined
poof-<version>-checksums.txtmanifest keylessly with Sigstore (cosign) in therelease-signingenvironment; - publishes the GitHub release with all assets, including the generated man page. Tags
containing
pre,beta,rc,alpha, ornightlyare marked as prereleases.
Channel fan-out
Publishing a GitHub release fans out to the package ecosystems:
| Channel | Workflow / repo | What it does |
|---|---|---|
| GitHub Releases | release.yml | Publishes pre-built binaries for manual download and installation from the GitHub Releases page |
| crates.io | crates.yml | cargo publish --locked from the release tag, after a tag/version match check (publish-crates environment) |
| Docker Hub | docker.yml | Multi-arch image (linux/amd64, arm64, arm/v7, riscv64, 386) from the Alpine Dockerfile, which installs the tagged release via install.sh; tagged <version>, <major>.<minor>, and latest, with max provenance |
| npm | npm.yml | Five packages built from the signed release archives, never rebuilding Rust: a @pirafrank/poof launcher that only spawns the native binary (no network access), plus four platform packages - Linux x64/arm64 (static musl) and macOS x64/arm64 - selected by SUPPORTED_TRIPLES in scripts/npm/common.py as a subset of the full list of native targets. Only an explicit allowlist of files from npm/ is staged; CI packs and publishes with Node 24 |
| MacPorts | macports.yml | Generates a Portfile with cargo2ports, test-installs it on macOS, and uploads it as an artifact; submission is manual (macports/macport_pr.sh). Not available in MacPorts yet: the new-port submission is pending review in macports-ports#31327 |
| Homebrew tap | pirafrank/homebrew-tap | External repo: renders the poof formula from the release assets and commits it to the tap; install with brew install pirafrank/tap/poof |
AUR (poof-bin) | pirafrank/aura | External repo: AURA generates PKGBUILD and .SRCINFO from the latest stable release and pushes them to poof-bin |
| APT / YUM / APK | pirafrank/packages | External repo: builds and signs .deb, .rpm, and .apk packages, served from pkg.fpira.com |
crates.io and Docker Hub skip prereleases; every channel can also be triggered manually via
workflow_dispatch.
The Homebrew, AUR, and APT/YUM/APK channels live in external repositories, not in the poof
repo. Their update workflows listen for repository_dispatch webhooks sent after a release
(update_formula, update_aur_package, and new_release respectively). All three are also
documented as install methods in Installation.
Continuous packaging surfaces
Two more packaging surfaces do not wait for a release:
- Nix flake (
flake.nix): builds poof from source on Linux and macOS (x86_64/aarch64);nix.ymlrunsnix flake checkon pull requests that touch Rust or flake files. - Devcontainer feature (
devcontainer-features/poof/):release_feature.ymlpublishes the feature to GHCR on every change to that directory onmainand opens an automated documentation PR.