- docs
- Publish and integrate
- Publish and integrate
- Publishing
- Bundle a release
Bundle a release
By the end of this page you have a tar archive and a sidecar metadata.json that ocx package push accepts. A package on the registry is two artefacts that travel together. One is the files your package needs at run time, and the other is the metadata that says how to install them. You need a directory of built files or an upstream release archive. The steps below cover what goes into the archive, how to compress it, and how to reuse a layer by its digest.
Choose what goes in the archive
Most upstream toolchains ship one root directory inside their archive, such as node-v24.21.0-linux-x64/bin/node. A package manager needs a flat surface, so the declared PATH entry (${self.installPath}/bin) lands in the consumer’s bin/ without knowing the upstream naming. Either pre-flatten the tree before you bundle, or keep the upstream layout and tell OCX to strip the wrapper at install time with strip_components. Keeping the layout avoids re-bundling cost. The repackaging guide walks through the common transformations.
To turn an upstream archive into a package in one step, let create unpack it and drop the wrapper directory:
ocx package create --extract --strip-components 1 node-v24.21.0-linux-x64.tar.xz -p linux/amd64 -m metadata.json -o node-24.21.0.tar.xzThe two strip_components forms differ in when they apply.
OCX assembles every installed package under content/ (three-tier storage), but that is the post-install layout and not a rule for your archive. The usual convention is bin/ for executables plus any data the binary reads at run time. Pair it with strip_components: 1 for upstreams that ship one wrapper directory. A single pre-built binary needs no wrapper, so set strip_components: 0 to land it at the archive root.
Keep the archive stable
ocx package create sorts entries by filename and writes deterministic tar headers, so mtime, owner and directory iteration order do not reach the archive. The same tree packed with the same OCX version and the same compression settings (codec, level, and single- or multi-threaded) gives the same bytes and digest, also after touch. File content, names and the executable bit count. Changing any of them, or the codec, level or thread mode, gives a new digest, so a rebuilt binary is a new layer. A different OCX version may also change the bytes.
Layer reuse depends on digest equality. A new layer in the registry means a new download for every consumer. Record the digest after the first push and reference it on later pushes, so an unchanged layer is not uploaded or pulled again:
ocx package create build -p linux/amd64 -m metadata.json -o mytool-1.0.0.tar.xzocx package push -p linux/amd64 -m metadata.json -i ghcr.io/acme/mytool:1.0.0 mytool-1.0.0.tar.xz
# Record the layer digest. The on-disk archive is the same blob the registry stores,# so a local sha256 matches the layer digest the registry will hold.BASE_DIGEST=$(sha256sum mytool-1.0.0.tar.xz | awk '{print $1}')
# Later releases reuse the layer by digest, with no re-bundle and no re-upload.ocx package push -p linux/amd64 -m metadata.json -i ghcr.io/acme/mytool:1.0.1 sha256:${BASE_DIGEST}.tar.xzThe sha256:<hex>.<ext> form on ocx package push points a new manifest at a layer that already lives in the registry. See Reusing layers across packages for the full pattern, including a stable base layer with a per-release top layer.
Choose the compression
The archive extension picks the codec:
.tar.xzuses LZMA and is the default. It gives noticeably smaller archives for binary payloads..tar.gzuses Gzip. It decompresses faster on tiny archives where CPU time dominates..tar.zstuses Zstandard (OCI 1.1). It is close to LZMA in size at its lower presets and decompresses several times faster, which helps on cold caches.
Layers download once and cache per digest (three-tier storage), so the size win usually outweighs the speed difference at registry scale. The compression level (fast, default, best) trades publish-time CPU for archive size. The threads flag (-j) parallelises LZMA and Zstandard compression, while Gzip stays single-threaded. A value of 0 auto-detects up to 16 cores.
Ship the sidecar metadata
ocx package create follows a sidecar convention so the metadata travels with the archive. Pass -m metadata.json and the command validates that file, resolves it and writes the result next to the output archive, named after the archive. The <stem>-receipt.json beside them is the build receipt that push and test read:
ocx package create build -p linux/amd64 -m metadata.json -o mytool-1.0.0.tar.xzThis produces:
mytool-1.0.0.tar.xzmytool-1.0.0-metadata.jsonsidecar, validated and rewritten in canonical formmytool-1.0.0-receipt.json
ocx package push uses the same convention in reverse. Omit -m from the push and OCX looks next to the first file layer for <stem>-metadata.json. You declare the metadata once at create time, and it follows the archive. The convention also names the output file when -o is a directory and -i and -p give the identifier and platform:
ocx package create build -i mytool:1.0.0 -p linux/amd64 -m metadata.json -o .This produces:
mytool-1.0.0-linux-amd64.tar.xzmytool-1.0.0-linux-amd64-metadata.jsonsidecar, picked up automatically by per-platform pushesmytool-1.0.0-linux-amd64-receipt.json
The pattern is <name>-<tag>-<os>-<arch>.tar.xz, where <name> is the last segment of the repository. So myorg/mytool:1.0.0 infers mytool-1.0.0-.... Inference with -o . always uses LZMA, so pass an explicit filename such as -o mytool-1.0.0.tar.gz for another codec. Per-platform pushes pick the names up automatically, as the multi-platform page shows. The ocx-mirror pipeline runs the same -o . convention in production.
Strip upstream wrappers
When you repackage an upstream archive, strip_components mirrors tar --strip-components. Declare it in metadata.json and OCX removes that many leading path segments while extracting each layer. A value of 1 collapses node-v24.21.0-linux-x64/bin/node to bin/node. The default is 0. The metadata reference lists every constraint.
{ "type": "bundle", "version": 1, "strip_components": 1}See also
ocx package createreference- Storage: packages and layers
- Publish a package for taking the bundle to the registry
- Repackage an upstream release for Homebrew, GitHub Releases and raw tarballs