Packslip

packslip

Work from the project's existing release workflow, artifact layout, and trust policy. Check packslip --version and the relevant subcommand's --help when flags differ from these examples.

Describe the release that was built

• On GitHub Actions, add jdx/packslip@v1 after the steps that build the final files and create the release. By default it attests the matched files, signs the release manifest with the job's OIDC identity, verifies it, and uploads only the bundle to the release. Upload the artifacts and any asset: files yourself first. Without the action, packslip create writes the signed bundle and uploads nothing.

• Pin the action to the full commit of its vX.Y.Z release. Its default CLI download is internally SHA-256 locked for every supported platform, then checked against the actual candidate build source and release-workflow provenance. The CLI/action tag still shares the final release commit. packslip-version explicitly overrides this internal lock (with a warning); set packslip-sha256 for a strict archive pin with that override. Checks run before extraction/execution. packslip-path supplies a local executable and bypasses archive/provenance checks. A source checkout without a release map requires one of these explicit trust overrides.

• Prefer two jobs, so the signing job cannot change the release. Run the action with upload: false in a job with these permissions:

  permissions:
    contents: read       # Download release assets; cannot change the release.
    id-token: write      # Sign with the workflow's OIDC identity.
    attestations: write  # Attest the files (the default attest: true).

  Upload the file at the action's bundle output with actions/upload-artifact, and attach it to the release from a second job that has contents: write. A contents: read token cannot see a draft release, so the action's download input cannot fetch its files. If the release stays a draft until the bundle is attached, download the build's files with actions/download-artifact and give their paths to the action's artifacts input instead. If the action instead runs as one step in an existing release job, it uploads the bundle itself, and that job needs contents: write in addition to the two write permissions above. See Publish with GitHub Actions for both layouts.

• By default the action uses the triggering tag as tag, that tag without a leading v as version, and github.sha as commit. When the job does not run on the release tag, as in a manual dispatch from a branch, pass tag and the tag's full commit SHA as commit. Pass version explicitly when the tag without a leading v is not semver, such as mytool-v1.2.3 or v4.1; the action does not normalize tags.

• Sign every release of a project from the same workflow file in the project's own repository. A consumer treats a release signed from a different workflow file as a new signer and refuses it until a person approves it, so run backfills from that file too. If releases must come from several workflow files of the repository, sign them with packslip create --no-pin-workflow. The action has no input for it (GitHub only warns about an input the action does not define and runs the step without it), so run packslip create in those jobs instead. Declare it from the first release: a consumer that accepted a release without it refuses the first one with it until a person approves it, and consumers that predate the field ignore it and still ask. See Workflow pinning.

• Select only installable binaries or archives as artifacts. Declare companion files as resources. Inspect archive contents before setting paths: --bin mytool discovers the executable within an archive, while --bin mytool=bin/tool uses an explicit path from the true archive root.

• Inspect inferred OS, architecture, libc, and format with packslip show. With packslip create, fix ambiguous metadata with an explicit artifact argument, such as dist/mytool.tar.gz:linux/x86_64/gnu, or PATH:any for a file that runs on every platform, or with a TOML manifest. The action's artifacts input takes only file paths and globs: set platforms in release.toml (the manifest input), and use the variants and formats inputs for those fields. Absent platform fields mean unrestricted, not unknown.

• Leave the main build of each platform (OS, architecture, and libc) without a variant, and give every other distinct build of that platform its own variant, whatever its format; consumers select only artifacts without a variant unless a user asks for one. Artifacts that differ only in format must contain the same build, because consumers pick among them by format preference.

• Do not list shared libraries; packslip create reads them from the executables it can open. Declare commands the program needs on PATH with --require bin:NAME[@MIN] (the action's require input), and put glibc_min or os_min on the artifact's requires in release.toml. See Host requirements.

Use CLI flags for shared metadata and a TOML manifest for per-artifact layouts, requirements, or resource scope. See Artifact configuration for release.toml examples, path rules, and every key.