A packslip is a signed release manifest for software distributed as archives,
installers, or executables. A release publishes one file,
packslip.sigstore.json (the release bundle), beside its artifacts. An
installer, package manager, or mirror verifies the bundle against the
project's signer. It then reads which artifact suits the host, where the
executables are inside that artifact, and the digest the download must match.
It need not guess from file names or trust a checksum file served next to the
binary. The format is stable at version 1.
Publish a release
Add these permissions and this step to a tag-triggered release job, after the workflow builds the artifacts and uploads them to the GitHub release:
permissions:
contents: write # Upload the bundle to the release.
id-token: write # Sign with the workflow's identity.
attestations: write # Attest the matched files.
steps:
- uses: jdx/packslip@v1
with:
artifacts: dist/*.tar.xz dist/*.zip
bin: mytool
The action attests the matched files and signs a statement of their digests,
platforms, and executable paths with the workflow's identity. It verifies the
bundle and uploads it to the release. It uploads no artifacts and needs no
long-lived signing key. Users can then install mytool with
packslip install github.com/owner/mytool instead of curl | sh.
Warning: this one-job form gives the action contents: write. To
keep the action away from release write access,
run it in a job with contents: read and upload the bundle from a separate job.
For CI other than GitHub Actions, see Publish from other CI.
Install a tool
packslip install replaces curl | sh with a verified install. It finds a
tool's signed release and checks it against the name you asked for. It
installs the complete archive and puts the declared commands in a bin
directory. It runs no downloaded code. After you
install packslip:
It supports GitHub projects and domain projects, which are named after a host,
such as mytool.example.com. It has no upgrade, list, or uninstall command.
See Bootstrap a tool.
Verify a release
When the bundle names a GitHub or GitLab project, packslip verify requires a
signer from that repository. It checks each --artifact against its digest in
the bundle:
The command trusts the project name the bundle claims, so check that the first
line of output begins ok: github.com/jdx/hk 2.3.0. To verify a domain
project, or to name the repository, signer fingerprint, or public key you
trust, see Verify a release.
Documentation
The documentation index lists every guide. Start with one of these:
- How packslip works and How trust works
- Try packslip locally with a local key and no CI account
- Publish with GitHub Actions, Release recipes, and Manage release lists
- Verify a release and Commit a verifier into your project
- Use packslip with mise
- Build an installer or mirror and Choose a library
- The specification, CLI reference, GitHub Actions reference, and JSON schemas
- The agent skill, which helps a coding agent configure a release, declare resources, and diagnose verification failures
Contributing
This repository holds the
specification source,
the CLI that publishes, verifies, and installs releases, and the Rust crate for
building consumers. It also holds two GitHub Actions: jdx/packslip publishes
a packslip, and jdx/packslip/releases builds a signed release list.
CONTRIBUTING.md
covers setup, checks, and documentation sources.
RELEASING.md covers
the maintainer release process. Report bugs and format feedback in
GitHub issues. Report a vulnerability
privately as SECURITY.md
describes.
Credits
Developed by Jeff Dickey (@jdx), author of mise, and Shunsuke Suzuki (@suzuki-shunsuke), author of aqua.
License
MIT; see LICENSE.