release.toml reference

For publishers writing the release.toml that packslip create --manifest (-m) reads: every key, its flag, and what create does when a key is absent. To write your first one, follow Describe your artifacts.

release.toml only configures packslip create. It is neither signed nor published, and consumers never read it: flags and release.toml produce the same signed release statement.

Layout

Top-level keys come first, then the tables. A table header such as [artifact.extensions."example.com"] belongs to the [[artifact]] entry above it, so place it right after that entry's keys.

project = "github.com/owner/mytool"
version = "1.2.3"
url_base = "https://github.com/owner/mytool/releases/download/v1.2.3"
bin = ["mytool"]

[source]
repo = "https://github.com/owner/mytool"
tag = "v1.2.3"

[extensions."example.com"]
build_id = "20260901.3"

[[artifact]]
path = "dist/mytool-1.2.3-linux-x64.tar.gz"
requires = { glibc_min = "2.31" }

[artifact.extensions."example.com"]
runner = "ubuntu-22.04"

[[artifact]]
path = "dist/mytool-1.2.3-darwin-arm64.tar.gz"

[[resource]]
kind = "man"
artifact = "mytool-1.2.3-linux-x64.tar.gz"
archive = "mytool-1.2.3/share/man/man1/mytool.1"

Keys in release.toml

Every flag is listed in packslip create.

Top-level keys

The [source] table

--commit and --tag need a repository from --source-repo or this table.

[[artifact]] tables

Each explicit os, arch, libc, variant, and format value is a lowercase word: a letter or digit, then letters, digits, ., _, or -. Platform values follow these rules:

• Explicit values are recorded exactly as written; only file names are translated. Write the vocabulary spellings: darwin (not macos), x86_64 (not amd64), and aarch64 (not arm64). create accepts :linux/amd64/gnu, but no consumer selects it.
• An absent platform field means the build does not depend on it. A universal macOS binary has os = "darwin" and no arch: it fits every Mac.
• any as arch or libc leaves that field out. os has no any: for a build that runs on every OS, set portable = true. os = "any" would be recorded as written and match no host.

Override the inferred platform shows the platform keys beside their argument forms.

Artifact argument suffixes

An artifact argument takes the suffixes in the Flag column above, with @VARIANT after the path or after a : suffix.

• A suffix is read only when it is well formed. Anything else stays part of the path, so colons in a timestamped directory name are safe.
• Each part of a suffix starts with a letter and holds only letters, digits, _, and -, such as fips or install_only.
• An @VARIANT suffix never contains a dot, so scoped@pkg-1.0.tgz stays a file name. The variant key accepts dots and a leading digit.

[[resource]] tables

Each [[resource]] table needs a kind and exactly one source key: archive, asset, repo, or exec.

Write a resource entry explains each kind and which qualifiers it takes.

Requirement keys

A requires table, top-level or per artifact, takes these keys; Declare host requirements explains each one.

Misspelled and repeated keys

A release.toml is refused when it:

• has an unknown key at the top level or in [source], [[artifact]], or [[resource]], with unknown field `bins`, expected one of …;
• lists the same artifact path twice, with artifact "dist/mytool.tar.gz" is listed twice.

Warning: Inside a requires table or a { name, path } entry of bin, packslip create ignores keys it does not know, so a misspelling such as glibc_mn is dropped without an error.

Flags with no key

Pass these next to --manifest: --key, --sign, --no-log, --out, --attested-by, --evidence, --no-sha512, --no-libs, and --no-pin-workflow.

How paths are resolved

How release.toml and flags combine

• --project, --version, --url-base, --notes-url, --published-at, --source-repo, --commit, and --tag replace the values in release.toml.
• Top-level bin and requires are defaults for every artifact, including command-line artifacts. An artifact's own bin or requires replaces the default as a whole, not field by field.
• --bin adds to the top-level bin; naming an executable in both records it twice.
• --require adds its commands to every artifact that has executables, on top of release.toml's requires.
• Command-line artifacts join the ones release.toml lists. When one has the same file name as an [[artifact]] entry, the entry is used and the argument is ignored, including any :platform or @variant suffix.
• --extension NAME=JSON replaces release.toml's whole value for NAME, keeping the other names.
• --url FILENAME=URL applies only where the entry for that file sets no url, and --format FILENAME=FORMAT only where the [[artifact]] entry sets no format.
• --provenance URLs are added to the entry's own provenance list, and --resource entries to the [[resource]] entries.

Under the GitHub Action, its inputs replace project, version, url_base, notes_url, and [source]; see How inputs reach packslip create.

How packslip create reads file names

create reads the OS, architecture, and format from the file name, ignoring case, for each one that release.toml, an argument suffix, or --format does not set. A portable artifact still takes its format from the name.

Operating system

The first row that matches wins.

A name with no OS records no os; Select platforms and variants lists this and other results create accepts without a warning.

Format

The format comes from the extension: .tar.xz, .tar.gz, .tar.zst, .tar.bz2, .tgz, .tar, .zip, .7z, .gz, .xz, .zst, .bz2, .deb, .rpm, .dmg, .pkg, .msix, .msi, .exe, or .AppImage. Vocabularies says how consumers install each one.

• A .exe is the program itself (raw) unless its name contains setup or install, which makes it an exe installer.
• A file with no extension is a raw executable when its OS is known or the artifact is portable.
• A dotted version is not an extension: mytool-1.2.3-linux-x64 has none.
• Any other file whose name gives no format, such as a .jar, is refused until you set format or --format FILENAME=FORMAT.

Architecture

• 386, ia32, a plain arm, the MIPS spellings, ppc64, and powerpc64 count only as separate words. A number inside a dotted version, as in mytool-1.386.0, is not an architecture.
• The MIPS and powerpc64 values follow Rust's target spellings and are outside the vocabularies.

An artifact for an OS other than macOS or Windows is refused when its name gives no architecture, since it would fit every host of that OS. Name one, or set any (PATH:linux/any, arch = "any") for a build that runs on every architecture. .noarch.rpm and _all.deb packages are exempt. A macOS or Windows artifact without one records no arch.

C library

The C library is the first of these that applies:

1. The explicit value: libc, or the third part of PATH:OS/ARCH/LIBC. any leaves the field out; set it for a Linux build that loads no C library, such as an archive of shell scripts.
2. No libc for an artifact whose OS is not Linux.
3. The file name: musl records musl; a word that is gnu or starts with gnueabi, gnuabi, gnux32, or glibc records gnu.
4. The listed executables, when every one is an ELF binary. A statically linked build, such as a Go binary built with CGO_ENABLED=0, records no libc and fits both glibc and musl hosts. A build that uses musl's loader records musl. Any other records gnu.
5. gnu, which does not fit a musl host. This happens when no executables are listed, an executable is a script, the format cannot be opened, or --no-libs is set.