Build an installer or mirror

This guide is for developers whose installer, package manager, or mirror consumes signed packslip releases. You will find, verify, and select a release, keep trust across installs, and sign a mirror's bundle.

For a ready-made installer, use packslip install (Bootstrap a tool); to check files by hand, use packslip verify (Verify a release); for the Rust API behind these steps, see Use the Rust crate.

Install a release

  1. Discover the release. List the project's versions, choose one, and locate its release bundle, as Discovery says:

    ProjectVersionsBundle
    Forge project on GitHubIts non-draft GitHub releases. Take each version from its tag (Tags), and its order and prerelease status from that version, never from GitHub's order or prerelease flag.The packslip*.sigstore.json asset whose statement has the predicateType https://packslip.dev/release/v1 and the requested project, or the same tool under the renamed repository. Compare owner and repository in any letter case.
    Domain projectIts signed release list at the well-known URL, once verified. Refuse a project with none.The URL in the chosen entry's packslip field.
    Forge project on gitlab.comThe specification defines none.A trusted publisher's list or your own configuration; otherwise refuse the project.

    If a GitHub repository carries a supplementary release list, verify it too. For each version it lists, the entry decides the tag, the status, and the bundle digest to accept; never choose a version it yanks.

    Warning: Never trust a bundle's file name for its type or project; read both from the statement.

  2. Verify the bundle alone against your pin before you use anything else it says.

    • When a release list entry names the bundle, refuse it before verifying unless its SHA-256 equals the digest the entry gives for that URL.
    • After verifying, check that the project is the one requested, or the same repository renamed. Check that the version is the one the list entry named or, without an entry, the tag named.
  3. Select an artifact from the verified result, never the unverified bundle. packslip verify --json lists every artifact with its signed digest; see Read the verified artifacts from a script. Choose one as Selecting an artifact says. Your installer decides which formats and resource kinds it supports.

  4. Check host requirements. Check the chosen artifact's requires as Checking requirements before installation says. Refuse only when a library, glibc, or OS version keeps the executables from starting. Warn about a missing or old command and any requirement you cannot check. Declare host requirements shows what publishers declare.

  5. Download, verify, and install. Download the artifact and verify it against the same bundle and pin before you unpack it. With the CLI, use packslip verify --artifact; see Check every file you use. Verify each resource asset you download the same way.

Implementations in other languages can test their artifact and resource selection, tag parsing, statement validation, forge identity, and signer fingerprints against the conformance vectors.

Use private hosts and mirrors

Once a signer is pinned, where a file came from does not change trust (How trust works). The exception is a keyless domain project's first use: its signer comes only from the list fetched over HTTPS from the project's host, never from a copy (rule 1 in Follow the consumer rules). packslip verify makes no network requests, so it works the same from an internal download host or across an air gap. When you call it or the crate, you fetch the bundle and artifacts and handle credentials, proxies, and caching.

Serve a vendor's release from your own host in two ways:

packslip install can use neither. It finds a bundle only through the project's own discovery and downloads the files that bundle names. It has no setting to point an artifact URL at another host. When a host the bundle names needs a token, see Download from a private host.

Repackage another vendor's release

A repackager signs its own release bundle for another vendor's files: for a vendor that publishes no packslip, or to mirror files a vendor's packslip covers. The bundle names the vendor's project and carries the vendor's digests, but lists your URLs and is signed with your identity, as Repackager attestation describes.

To mirror a vendor release whose verified bundle you saved as vendor/packslip.sigstore.json:

vendor_sha256=$(sha256sum vendor/packslip.sigstore.json | cut -d ' ' -f 1)
packslip create \
  --project mytool.example.com \
  --version 1.2.3 \
  --attested-by repackager \
  --evidence "vendor-packslip=$vendor_sha256" \
  --url-base https://mirror.example.net/mytool/1.2.3/ \
  --bin mytool \
  --key mirror.key \
  --out mirror \
  dist/mytool-1.2.3-linux-x86_64.tar.gz

--evidence without --attested-by repackager fails with --evidence describes what a repackager checked; pass --attested-by repackager. Neither flag has a release.toml equivalent; pass both even with --manifest.

A verified repackager bundle establishes that the repackager signed these digests and what it says it checked. It does not establish anything on the vendor's behalf: consumers must trust the repackager's signer explicitly and rank its bundle below a vendor packslip. A consumer whose last accepted release was vendor-attested asks a person before accepting yours (No-downgrade and approvals).

With the CLI, a consumer verifies your key-signed bundle with --pubkey mirror.pub alone. For a keyless one, see Verify a repackager's release.

If you also publish a release list of your bundles, record each check you made on a listed release with packslip releases --evidence URL=KIND[=DETAIL], once per check. Publish a list as a stamping host covers lists from publishers other than the vendor.

Follow the consumer rules

A successful packslip verify alone does not meet the consumer rules, the complete contract for an install. packslip verify and the crate's verify_forge, select_artifact, and select_resources cover verification and selection. The crate's installer modules also check list freshness, choose versions, enforce no-downgrade, and check host requirements, with APIs shaped for packslip install. Beyond the Install a release steps, your code handles each rule:

  1. Pin the identity once. For a forge project, take the first pin from the name: accept only the forge's issuer and a certificate whose source repository is that repository (packslip verify with no trust flags and verify_forge do this). Then remember the repository ID it records; the ID holds across renames and transfers. Take other projects' pins from your configuration or, on a keyless domain project's first use, from the list fetched over HTTPS from its host. Add any signer fingerprint you read independently to the first pin. Take a public key only from your own pins, never from the bundle or its key hint. Trust another publisher's list per host, through configuration. See First use and signer fingerprints.
  2. Verify the bundle and downloaded files. Pass --allow-unlogged, or in Rust require_log: false, only when the user explicitly accepted unlogged releases.
  3. Enforce no-downgrade. Ask a person before accepting a signer change, relaxed workflow pinning, or another weakening the rule lists, compared with the last accepted release across renames; see No-downgrade and approvals.
  4. Apply the minimum release age. Measure it from the authenticated log integration time, which the verifier reports as logged_at. Use published_at only for an unlogged bundle the user deliberately accepted.
  5. Use the project's discovery metadata. Refuse an expired list, a list whose sequence is below the last you accepted, and a project whose accepted list has gone missing. Never select a yanked entry. Skip prereleases unless asked, rank by semver precedence, and follow Latest for an unconstrained request. Apply any stamping-host policy you configured.
  6. Select one artifact. Step 3. Refuse a tie the preferences leave unresolved; host requirements never break one. In Rust, select_artifact does this (pass the formats you can unpack).
  7. Check host requirements before installing. Step 4; in Rust, install_host checks requires.
  8. Install resources. Apply Resources: keep each resource's most specific entries that fit the artifact, and take each from its strongest available source. Run vendor code only as Running an exec entry permits. Ignore unknown kinds. Report a resource you cannot fetch and finish without it; fail on a digest mismatch.

Keep trust state between installs

Keep, for each project, the remembered state the consumer rules list:

A lockfile can carry a project's pin with artifact URLs and digests, so another machine enforces it on its first install. Local state can separately remember signer history and list sequences. The specification leaves where to store either to you. One consumer, mise, keeps both; see Preserve trust across upgrades and machines.

For the vendor's side (publishing a list, withdrawing versions, and recommending a default), see Manage release lists.