Skip to content

Releases: prebuilt artifacts, checksums, signatures, SBOM, reproducible builds #146

Open

Description

@Kinflou

Part of ComlineProject/core#227. Proposal: ComlineProject/docs#163, proposals/offline/supply.md#tooling-into-the-gap.

For sealed networks the CLI needs:

  • prebuilt binaries per platform, with checksums and signatures;
  • reproducible builds: rebuild from source and compare bytes, as comline-typescript does for its wasm core;
  • an SBOM per release.

Related: #1 (publish to crates.io).

Decided (docs#163):

  • Signing: minisign over a checksums file is the primary signature, because it can be checked with one public key and no network. GitHub artifact attestations (sigstore) come on top, for provenance.
  • SBOM: CycloneDX JSON (cargo-cyclonedx). SPDX only if someone asks for it.

Done (#159)

  • .github/workflows/release.yml: on a v* tag it checks the tag against the Cargo.toml version and builds comline for five targets (x86_64-unknown-linux-musl and aarch64-unknown-linux-musl, static and smoke-tested on Debian 9 and busybox; aarch64-apple-darwin, x86_64-apple-darwin; x86_64-pc-windows-msvc).
  • Each build is packaged as comline-<target>.tar.gz (.zip on Windows), with a SHA256SUMS.
  • Each archive is attested with GitHub build provenance.
  • A draft GitHub Release is created for a person to publish.
  • Cargo.toml has [package.metadata.binstall], so cargo binstall --git https://github.com/ComlineProject/cli comline finds the archives. A glibc host falls back to the musl archive.

Left to do

  • Signing with minisign, as decided above: one signature over SHA256SUMS, plus per-archive .sig files if binstall's signature check needs them.
    • The user generates the key pair. The secret key and its password go in as MINISIGN_SECRET_KEY and MINISIGN_PASSWORD, scoped to a release environment.
    • The public key goes in [package.metadata.binstall.signing], the README and RELEASING.md.
    • The release job checks the signatures against that public key and fails if they don't match. It never releases unsigned.
    • PR CI tests signing and verification with a throwaway key, including a tampered archive that must fail.
    • RELEASING.md describes key rotation and how to verify a download by hand.
  • SBOM: CycloneDX JSON from cargo-cyclonedx, attached to the release, and signed and checksummed with the archives.
  • Reproducible builds: rebuild from source and compare the bytes.
  • First real tag (v0.2.0 or later) exercises the Attest and Draft release jobs, which PR CI skips. Afterwards, check cargo binstall --git … comline against the published release on each OS.
  • Docker Hub pulls: the smoke job pulls debian:9 and busybox from Docker Hub, which can hit rate limits. Mirror them to GHCR if that happens.
  • crates.io-based binstall (cargo binstall comline without --git) waits on Publish comline to crates.io #1.

Activity

  1. Kinflou commented on Nov 9, 2026

    @Kinflou
    MemberAuthor

    Decided (docs#163):

    • Signing: minisign over a checksums file is the primary signature, because it can be checked with one public key and no network. GitHub artifact attestations (sigstore) come on top, for provenance.
    • SBOM: CycloneDX JSON (cargo-cyclonedx). SPDX only if someone asks for it.
  2. Kinflou commented on Nov 14, 2026

    @Kinflou
    MemberAuthor

    Progress (2026-11-15). #159 added .github/workflows/release.yml. On a v* tag it does the following:

    • checks that the tag matches the Cargo.toml version;
    • builds comline for five targets:
      • x86_64-unknown-linux-musl and aarch64-unknown-linux-musl, static, built in the ci-tools image. They are smoke-tested on Debian 9 (glibc 2.24) and on busybox (uclibc).
      • aarch64-apple-darwin and x86_64-apple-darwin;
      • x86_64-pc-windows-msvc;
    • packages each build as comline-<target>.tar.gz, or .zip on Windows;
    • writes a SHA256SUMS;
    • attests each archive with GitHub build provenance;
    • creates a draft GitHub Release for a person to publish.

    Cargo.toml has [package.metadata.binstall], so cargo binstall --git https://github.com/ComlineProject/cli comline will find the archives. A glibc host falls back to the musl archive.

    Left to do

    • Signing with minisign, as decided above: one signature over SHA256SUMS, plus per-archive .sig files if binstall's signature check needs them.
      • The user generates the key pair. The secret key and its password go in as MINISIGN_SECRET_KEY and MINISIGN_PASSWORD, scoped to a release environment.
      • The public key goes in [package.metadata.binstall.signing], the README and RELEASING.md.
      • The release job checks the signatures against that public key and fails if they don't match. It never releases unsigned.
      • PR CI tests signing and verification with a throwaway key, including a tampered archive that must fail.
      • RELEASING.md describes key rotation and how to verify a download by hand.
    • SBOM: CycloneDX JSON from cargo-cyclonedx, attached to the release, and signed and checksummed with the archives.
    • Reproducible builds: rebuild from source and compare the bytes.
    • First real tag (v0.2.0 or later) exercises the Attest and Draft release jobs, which PR CI skips. Afterwards, check cargo binstall --git … comline against the published release on each OS.
    • Docker Hub pulls: the smoke job pulls debian:9 and busybox from Docker Hub, which can hit rate limits. Mirror them to GHCR if that happens.
    • crates.io-based binstall (cargo binstall comline without --git) waits on Publish comline to crates.io #1.
  3. Kinflou commented on Nov 15, 2026

    @Kinflou
    MemberAuthor

    Rewrote the body: the old text said the only install path is cargo install --path ., which has not been true since #159 (release workflow, static musl builds, SHA256SUMS, build-provenance attestations, binstall metadata). The body now carries the decisions, what #159 did (ticked) and the remaining checklist from the 2026-11-15 progress comment (minisign, SBOM, reproducible builds, first real tag, Docker Hub mirror, crates.io binstall). Original is in the edit history.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Soon

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions