Artifact Reference#

Every cs build writes a runtime plus metadata files. The runtime is the final stamped binary artifact. Downstream signing and attestation workflows run after conda-ship writes these files.

Layouts#

Layout

Runtime

Bundle file

Network during bootstrap

online

RUNTIME

none

yes

external

RUNTIME

RUNTIME.bundle.tar.zst

optional

embedded

RUNTIMEz

embedded in binary

no

On Windows, binary filenames also include .exe.

Bundle Contents#

Bundles are a transport for the conda package archives already named in the runtime lock. They are not channel mirrors and do not use a linux-64/ or noarch/ directory layout.

external and embedded bundles contain top-level .conda and .tar.bz2 package archive files. The runtime matches those filenames against the stamped lockfile and verifies package SHA256 values before installing from them.

External bundle directories may contain unrelated files, but conda-ship only indexes top-level conda package archives and skips symbolic links. Embedded bundles are stricter because they are extracted from a tar archive: every entry must be a top-level regular .conda or .tar.bz2 file. Directory entries, nested paths, symbolic links, hard links, and other file types are rejected.

Metadata Files#

For an online build with runtime demo, conda-ship stages:

  • demo or demo.exe

  • demo.runtime.lock

  • demo.packages.txt

  • demo.info.json

  • demo.sha256

When --target-label is used, the label is inserted into the stem, for example demo-linux-64.info.json.

For an embedded build, the stem uses the z suffix, for example demoz.info.json or demoz-linux-64.info.json.

For an external build, conda-ship also stages demo.bundle.tar.zst or a target-qualified equivalent.

Stamped Runtime Data#

conda-ship appends a runtime data block to every staged runtime. The block contains the runtime lock, runtime name, delegate executable, install scheme, install name, docs URL, bundle environment variable names, and the embedded bundle bytes for embedded builds.

The data block ends with:

  • format version

  • header length

  • bundle length

  • header SHA256

  • bundle SHA256, or the SHA256 of empty bytes when no embedded bundle is present

  • conda-ship runtime-data magic bytes

The generated runtime validates the stamped header at startup. For embedded artifacts, it also verifies the bundle checksum before extracting package archives during bootstrap.

The binary checksum in .sha256 covers the final stamped artifact. The conda-ship release workflow also publishes GitHub Artifact Attestations for the cs CLI, runtime templates, and SHA256SUMS manifest.

Verify a downloaded release asset with:

gh attestation verify ./cs-x86_64-unknown-linux-gnu \
  -R jezdez/conda-ship \
  --signer-workflow jezdez/conda-ship/.github/workflows/release.yml

Downstream distributions can add their own attestations or platform signing after conda-ship finishes staging their runtime artifacts.

Info JSON#

The info JSON contains:

  • schema version

  • artifact name

  • layout

  • conda platform

  • runtime filename

  • optional external bundle filename

  • lock filename

  • package list filename

  • package count

  • SHA256 checksums

Package List#

The package list is tab-separated and contains:

  • package name

  • version

  • build string

  • package URL

  • SHA256, when available from the lockfile