Releases and compatibility

Learn what a release contains, how to verify it, and which interfaces will receive compatibility guarantees.

What is promised today

pistra has no tagged releases or formal compatibility guarantees yet.

Expect additive changes such as configuration keys, detectors, and endpoints. Do not rely on that expectation as a guarantee. Pin an image digest, read the changelog, and test upgrades.

The first tagged release will define each promised surface and the version where that promise starts.

What a tagged release produces

Verify artifacts by immutable image digest. A tag can move, so a signature over a tag does not identify one build.

image	multi-arch on GHCR, carrying the optional native detector tier, built from the same Dockerfile the chart’s README tells operators to build
signature	cosign sign over the image digest, keyless via the runner’s OIDC identity, no key to store, and none to rotate
SBOM	SPDX and CycloneDX, generated from the image rather than from source, so it covers the distroless base’s Debian packages as well as the Go modules; attested to the digest with cosign attest
binaries	tar.gz, deb and rpm for linux and darwin on amd64 and arm64, with one cosign signature over the checksum file that covers all of them
tokenizer shim	its own per-target artifact, so the native tier can be run outside a container
licence report	a third-party licence inventory, because “what is in it” is a question a commercial licence invites
chart	pushed as an OCI artifact to the same registry

The SBOM is generated from the image so it includes base-image packages.

Which build is this

Run this command:

$ pistra version

The command prints the version, commit, and build date. A working-tree build prints devel and its commit.

For a build you did not make, verify the signature and SBOM attestation against its digest.

The surfaces a promise would cover

These are the interfaces a deployment depends on. They have no stability guarantee yet. Each is generated from code or checked for drift.

• Configuration, api/config.schema.json and the configuration reference, both generated from the config structs. A key cannot change without the schema and the page changing with it.
• Commands and flags, the command-line reference, generated from the usage blocks and flag declarations in the binary, so a flag cannot be renamed without the page renaming with it.
• Admin API, api/openapi.yaml, generated from the handlers. Manage configuration through the API describes what most deployments automate against it.
• Audit records, the record format and the chain over it, which pistra audit verify checks without trusting the node that wrote it. See the audit trail.
• Metric names, held to the registry by a drift test, so a renamed series breaks the build rather than a dashboard.
• Entity vocabulary, the entity types a detector may emit, checked at load. See PII coverage.

What changed, in two records

Use two records because they answer different questions.

Read CHANGELOG.md before an upgrade. It lists changes that affect configuration or results, grouped by impact.

Search the generated release notes when you need to find a specific commit or pull request. They list every change in a tagged release.